humanish 0.107.0 → 0.109.0

package/dist/cli/commands/analyze.js

@@ -5,7 +5,7 @@ import { analyzeRun, correctAnalysis, dryRunBundleRefusal, showAnalysis, } from
 import { listAnalyses } from "../../analysis/store.js";
 import { listAnalysisExecutions } from "../../analysis/store-executions.js";
 import { resolveRunPath } from "../../run/locate.js";
-import { discoverCliKeys, JSON_OPTION_DESCRIPTION, writeResult } from "../io.js";
+import { CWD_OPTION_DESCRIPTION, discoverCliKeys, JSON_OPTION_DESCRIPTION, RUN_OPTION_DESCRIPTION, writeResult, humanError, } from "../io.js";
 import { resolvePhysicalCwd } from "../../run/paths.js";
 /** Commander may collect a shared flag on the parent; only explicit values override leaf defaults. */
 function analysisSelection(options, command) {
@@ -24,11 +24,11 @@ export function registerAnalyzeCommand(parent, io) {
         .command("analyze")
         .enablePositionalOptions()
         .description("Analyze retained participant evidence into versioned findings. Selected text and captures go to the chosen remote analyst. Opening Observer never starts analysis.")
-        .summary("Generate evidence-linked study findings.")
-        .option("--run <id>", "Completed run id or latest pointer.", "latest")
-        .option("--cwd <path>", "Target project directory.", ".")
+        .summary("Analyze a live run into evidence-linked findings.")
+        .option("--run <id>", RUN_OPTION_DESCRIPTION, "latest")
+        .option("--cwd <path>", CWD_OPTION_DESCRIPTION, ".")
         .option("--provider <name>", "Analyst: openai (default) or restricted codex account. No provider fallback.")
-        .option("--max-cost <usd>", "Required for OpenAI, including dry-run: USD admission estimate ceiling, not a billing cap. Unsupported for Codex.")
+        .option("--max-cost <usd>", "Required for OpenAI, also with --dry-run: send nothing when the estimated cost in USD is above this. The estimate is not a billing cap. Unsupported for Codex.")
         .option("--model <id>", "Supported vision model. OpenAI uses high effort; qualified Codex account analysis uses low effort.", DEFAULT_ANALYSIS_MODEL)
         .option("--question <text>", "Additional reviewer question; does not change participant instructions.")
         .option("--timeout-ms <ms>", "Request timeout, at most 600000 ms.", String(DEFAULT_ANALYSIS_TIMEOUT_MS))
@@ -40,23 +40,23 @@ export function registerAnalyzeCommand(parent, io) {
     analyze
         .command("list")
         .description("List immutable analysis versions, including failed attempts.")
-        .option("--run <id>", "Run id or latest pointer.", "latest")
-        .option("--cwd <path>", "Target project directory.", ".")
+        .option("--run <id>", RUN_OPTION_DESCRIPTION, "latest")
+        .option("--cwd <path>", CWD_OPTION_DESCRIPTION, ".")
         .option("--json", JSON_OPTION_DESCRIPTION)
         .action((options, command) => handleAnalyzeList(io, options, command));
     analyze
         .command("show")
         .description("Read validated analysis and correction history. Defaults to the latest usable version.")
-        .option("--run <id>", "Run id or latest pointer.", "latest")
+        .option("--run <id>", RUN_OPTION_DESCRIPTION, "latest")
         .option("--id <id>", "Exact analysis version.")
-        .option("--cwd <path>", "Target project directory.", ".")
+        .option("--cwd <path>", CWD_OPTION_DESCRIPTION, ".")
         .option("--json", JSON_OPTION_DESCRIPTION)
         .action((options, command) => handleAnalyzeShow(io, options, command));
     analyze
         .command("correct")
         .description("Append a human review note bound to one exact finding version; original claims remain intact.")
-        .option("--run <id>", "Run id or latest pointer.", "latest")
-        .option("--cwd <path>", "Target project directory.", ".")
+        .option("--run <id>", RUN_OPTION_DESCRIPTION, "latest")
+        .option("--cwd <path>", CWD_OPTION_DESCRIPTION, ".")
         .requiredOption("--analysis <id>", "Analysis version to review.")
         .requiredOption("--finding <id>", "Finding to review.")
         .addOption(new Option("--status <status>", "Review disposition.")
@@ -83,7 +83,7 @@ async function handleAnalyze(io, options, command) {
     if (!selected.ok || !selected.config) {
         const refusal = await dryRunBundleRefusal(await resolvePhysicalCwd(options.cwd), options.run, options.dryRun === true);
         if (refusal) {
-            writeResult(command, io, refusal, (value) => forTerminal(`${value.error?.message ?? ""}\n${value.error?.code ?? ""}\n`));
+            writeResult(command, io, refusal, (value) => humanError(value.error));
             io.setExitCode(2);
             return;
         }
@@ -99,7 +99,7 @@ async function handleAnalyze(io, options, command) {
                 message: selected.ok ? "Analysis is disabled." : selected.message,
             },
         };
-        writeResult(command, io, result, (value) => `${value.error.message}\n`);
+        writeResult(command, io, result, (value) => humanError(value.error));
         io.setExitCode(2);
         return;
     }
@@ -126,8 +126,6 @@ async function handleAnalyze(io, options, command) {
             if (value.ok && value.dryRun)
                 return `Admission estimate: $${value.admission?.estimatedCostUsd ?? "unknown"}; output allowance: ${value.admission?.outputTokenAllowance ?? "unknown"} tokens including reasoning. No request sent.\n`;
             const lines = [];
-            if (!value.ok)
-                lines.push(value.error?.message ?? "Analysis unavailable.", value.error?.code ?? "");
             if (value.artifactPath)
                 lines.push(`${value.reused ? "Reused" : "Saved"} ${value.status} analysis: ${value.artifactPath}`);
             if (value.executionReceiptPath)
@@ -141,7 +139,12 @@ async function handleAnalyze(io, options, command) {
             if (value.reused)
                 lines.push("No new request sent.");
             lines.push(...value.warnings);
-            return forTerminal(lines.filter(Boolean).join("\n") + "\n");
+            const stdout = lines.length === 0 ? "" : forTerminal(lines.join("\n") + "\n");
+            // A failed analysis keeps its artifact and usage lines on stdout; the error goes to stderr.
+            if (value.ok)
+                return stdout;
+            const error = value.error ?? { message: "Analysis unavailable." };
+            return { ...(stdout ? { stdout } : {}), error };
         });
         io.setExitCode(result.ok ? 0 : 2);
     }

package/dist/cli/commands/codex.js

@@ -3,22 +3,23 @@ import { resolve } from "node:path";
 import { Command, Option } from "commander";
 import { startCodexAppServerUi } from "../../actors/codex/app-server-ui.js";
 import { redactText } from "../../evidence/redaction.js";
-import { JSON_OPTION_DESCRIPTION, parseObserverPort, parseTimeoutMs, writeResult, } from "../io.js";
+import { CWD_OPTION_DESCRIPTION, freePortOption, JSON_OPTION_DESCRIPTION, parseObserverPort, parseTimeoutMs, writeResult, humanError, } from "../io.js";
 export function registerCodexCommands(parent, io) {
+    // Hidden from --help and the CLI reference: it drives a Codex app-server session directly and
+    // is not a step in running or reviewing a study.
     const codex = parent
-        .command("codex")
-        .description("Run Codex-native humanish integration surfaces.")
-        .summary("Run Codex-native humanish integration surfaces.");
+        .command("codex", { hidden: true })
+        .description("Run Codex-native humanish integration surfaces.");
     codex
         .command("app-server")
         .description("Run a browser-visible Codex app-server actor surface and write redacted protocol artifacts.")
-        .option("--cwd <path>", "Target project directory.", ".")
+        .option("--cwd <path>", CWD_OPTION_DESCRIPTION, ".")
         .option("--prompt <text>", "Prompt to submit to Codex app-server.")
         .option("--prompt-file <path>", "Read the Codex app-server prompt from a file.")
         .option("--run-root <path>", "Artifact directory for redacted app-server evidence.")
         .option("--state-file <path>", "State JSON file for external observers.")
         .option("--timeout-ms <ms>", "Actor timeout in milliseconds.", String(900_000))
-        .option("--port <port>", "Local browser UI port.", "0")
+        .addOption(freePortOption())
         .option("--model <model>", "Optional Codex model override.")
         .addOption(new Option("--sandbox <mode>", "Turn sandbox policy.")
         .choices(["read-only", "workspace-write", "danger-full-access"])
@@ -101,9 +102,8 @@ export function registerCodexCommands(parent, io) {
     });
 }
 function formatCodexAppServerUiHuman(result) {
-    if (!result.ok) {
-        return `${result.error?.code}: ${result.error?.message}\n`;
-    }
+    if (!result.ok)
+        return humanError(result.error);
     return ([
         "humanish codex app-server",
         `url: ${result.url ?? "not-started"}`,

package/dist/cli/commands/comms.js

@@ -3,18 +3,18 @@ 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 { resolveStudyManifest } from "../../study/discover.js";
 import { runCommsCatchHost } from "../../comms/catch-host.js";
 import { DEFAULT_SANDBOX_CATCH_PORT } from "../../comms/sandbox-catch.js";
-import { applyEnvFileOption, JSON_OPTION_DESCRIPTION, writeResult } from "../io.js";
+import { applyEnvFileOption, CWD_OPTION_DESCRIPTION, ENV_FILE_OPTION_DESCRIPTION, JSON_OPTION_DESCRIPTION, PORT_OPTION_DESCRIPTION, writeResult, messageOutput, } from "../io.js";
 export function registerCommsCommands(parent, io) {
     const comms = parent
         .command("comms")
         .description("Local email capture, real receiving connections, checks and cleanup recovery.")
-        .summary("Off-app comms surfaces.");
+        .summary("Catch the email an app sends, for email-gated flows.");
     comms
         .command("providers")
         .description("List installed communication provider capabilities. No network requests.")
@@ -22,61 +22,61 @@ export function registerCommsCommands(parent, io) {
         .action((_options, command) => handleCommsProviders(io, _options, command));
     const connections = comms
         .command("connections")
-        .description("Manage project-local non-secret connection profiles. A lab explicitly selects its receiving connection.");
+        .description("Manage project-local non-secret connection profiles. A study explicitly selects its receiving connection.");
     connections
         .command("list")
         .description("Show saved connections and local credential status; does not authenticate with a provider.")
-        .option("--cwd <path>", "Target project directory.", ".")
-        .option("--env-file <path>", "Load credentials for local status without printing values.")
+        .option("--cwd <path>", CWD_OPTION_DESCRIPTION, ".")
+        .option("--env-file <path>", ENV_FILE_OPTION_DESCRIPTION)
         .option("--json", JSON_OPTION_DESCRIPTION)
         .action((options, command) => handleCommsList(io, options, command));
     connections
         .command("add")
         .argument("[name]", "Project connection name.", "agentmail")
-        .description("Save an AgentMail connection profile. Does not write a key, alter a lab or contact the provider.")
-        .option("--cwd <path>", "Target project directory.", ".")
+        .description("Save an AgentMail connection profile. Does not write a key, alter a study or contact the provider.")
+        .option("--cwd <path>", CWD_OPTION_DESCRIPTION, ".")
         .option("--provider <id>", "Installed provider id.", "agentmail")
-        .option("--api-key-env <name>", "Environment variable NAME, never its value.", "AGENTMAIL_API_KEY")
+        .option("--api-key-env <name>", "The name of an environment variable, never its value.", "AGENTMAIL_API_KEY")
         .option("--json", JSON_OPTION_DESCRIPTION)
         .action((name, options, command) => handleCommsAdd(io, name, options, command));
     comms
         .command("check")
         .description("Check connection and credential presence; --online authenticates without creating inboxes.")
-        .option("--cwd <path>", "Target project directory.", ".")
+        .option("--cwd <path>", CWD_OPTION_DESCRIPTION, ".")
         .option("--connection <name>", "Saved connection name.", "agentmail")
-        .option("--lab <path>", "Check the connection selected by this exact lab.")
+        .option("--study <path>", "Check the connection this study selects.")
         .option("--online", "Make a read-only provider authentication request.")
-        .option("--env-file <path>", "Load credentials without printing values.")
+        .option("--env-file <path>", ENV_FILE_OPTION_DESCRIPTION)
         .option("--json", JSON_OPTION_DESCRIPTION)
         .action((options, command) => handleCommsCheck(io, options, command));
     comms
         .command("configure")
-        .description("Preview or save a local receiving-enabled copy of a supported lab. No provider requests.")
-        .requiredOption("--lab <path>", "Exact source lab path or handle.")
-        .option("--cwd <path>", "Target project directory.", ".")
+        .description("Preview or save a local receiving-enabled copy of a supported study. No provider requests.")
+        .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; original lab remains unchanged.")
+        .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)
         .action((options, command) => handleCommsConfigure(io, options, command));
     comms
         .command("recover")
         .description("Inspect interrupted email leases; --apply deletes only privately recorded resources owned by this project and account.")
-        .option("--cwd <path>", "Target project directory.", ".")
+        .option("--cwd <path>", CWD_OPTION_DESCRIPTION, ".")
         .option("--run <id>", "One run to inspect or recover.")
         .option("--apply", "Recover the selected inactive run and verify mailbox deletion.")
-        .option("--env-file <path>", "Load credentials without printing values.")
+        .option("--env-file <path>", ENV_FILE_OPTION_DESCRIPTION)
         .option("--json", JSON_OPTION_DESCRIPTION)
         .action((options, command) => handleCommsRecover(io, options, command));
     comms
         .command("catch")
-        .description("Run the email catch on this host so humanish can study an app it does not provision. Your app posts its email sends here; the persona opens /inbox; humanish drains GET /deliveries and writes digest-only evidence. Point your lab's comms.email.external.catchBaseUrl at this server.")
-        .summary("Run the adopter-hosted email catch.")
-        .option("--port <port>", "Port for capture + inbox (default 8025).", String(DEFAULT_SANDBOX_CATCH_PORT))
+        .description("Run the email catch on this host so humanish can study an app it does not provision. Your app posts its email sends here; the persona opens /inbox; humanish drains GET /deliveries and writes digest-only evidence. Point your study's comms.email.external.catchBaseUrl at this server.")
+        .summary("Run the email catch on this host.")
+        .option("--port <port>", PORT_OPTION_DESCRIPTION, String(DEFAULT_SANDBOX_CATCH_PORT))
         .option("--dir <path>", "Directory for the deliveries log and rendered inbox.", ".humanish/comms-catch")
         .option("--token <value>", "Require this bearer token, at least 16 characters, on GET /deliveries (recommended when reachable off-host).")
         .option("--smtp-port <port>", "Also capture SMTP mail on 127.0.0.1:<port>. Point your app's SMTP transport here.")
-        .option("--inbox-port <port>", "Also serve a READ-ONLY inbox listener on 0.0.0.0:<port>, so a persona on another machine can open /inbox. Without it the catch stays loopback-only.")
+        .option("--inbox-port <port>", "Also serve a read-only inbox listener on 0.0.0.0:<port>, so a persona on another machine can open /inbox. Without it the catch stays loopback-only.")
         .option("--recipient <address>", "Only render mail sent to this address (repeatable). Default: render whatever the app actually mailed.", (value, previous) => [...(previous ?? []), value])
         .action((options) => handleCommsCatch(io, options));
 }
@@ -102,25 +102,32 @@ async function handleCommsAdd(io, name, options, command) {
             ? await saveCommsConnection(resolve(options.cwd), name, options.apiKeyEnv)
             : { ok: false, message: "Only AgentMail connection setup is currently available." }),
     };
-    writeResult(command, io, result, (value) => `${value.message}\n`);
+    writeResult(command, io, result, messageOutput);
     io.setExitCode(result.ok ? 0 : 2);
 }
 async function handleCommsCheck(io, options, command) {
     if (!(await applyEnvFileOption({ command, cwd: options.cwd, envFile: options.envFile, io })))
         return;
     let connection = options.connection;
-    if (options.lab) {
-        const lab = await resolveLabManifest(options.cwd, options.lab);
-        if (!lab.ok || lab.config.comms?.email?.kind !== "real") {
+    const study = options.study;
+    if (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 lab 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, (value) => `${value.message}\n`);
+            writeResult(command, io, result, messageOutput);
             io.setExitCode(2);
             return;
         }
-        connection = lab.config.comms.email.connection;
+        connection = resolved.config.comms.email.connection;
     }
     const result = await checkCommsConnection({
         cwd: resolve(options.cwd),
@@ -128,12 +135,18 @@ async function handleCommsCheck(io, options, command) {
         env: process.env,
         online: options.online === true,
     });
-    writeResult(command, io, result, (value) => `${value.message}\n`);
+    writeResult(command, io, result, messageOutput);
     io.setExitCode(result.ok ? 0 : 2);
 }
 async function handleCommsConfigure(io, options, command) {
-    const result = await configureCommsLab({ ...options, cwd: resolve(options.cwd) });
-    writeResult(command, io, result, (value) => `${value.message}\n`);
+    const result = await configureCommsStudy({
+        cwd: resolve(options.cwd),
+        study: options.study,
+        connection: options.connection,
+        ...(options.apply === undefined ? {} : { apply: options.apply }),
+        ...(options.planToken === undefined ? {} : { planToken: options.planToken }),
+    });
+    writeResult(command, io, result, messageOutput);
     io.setExitCode(result.ok ? 0 : 2);
 }
 async function handleCommsRecover(io, options, command) {
@@ -165,7 +178,7 @@ async function handleCommsRecover(io, options, command) {
                 adapter,
             })),
         };
-        writeResult(command, io, result, (value) => `${value.message}\n`);
+        writeResult(command, io, result, messageOutput);
         io.setExitCode(result.ok ? 0 : 2);
     }
     catch {
@@ -174,7 +187,7 @@ async function handleCommsRecover(io, options, command) {
             ok: false,
             message: "Recovery could not complete. Select one recorded run with --run, check its connection, and retry. No unrecorded resources are eligible.",
         };
-        writeResult(command, io, result, (value) => `${value.message}\n`);
+        writeResult(command, io, result, messageOutput);
         io.setExitCode(2);
     }
 }

package/dist/cli/commands/feedback.js

@@ -1,24 +1,24 @@
 import { Command } from "commander";
 import { draftFeedback, listFeedback, renderIssueMarkdown, renderIssueUrl, verifyFeedback, } from "../../feedback/feedback.js";
-import { candidateOption, JSON_OPTION_DESCRIPTION, wantsJson, writeResult, } from "../io.js";
+import { candidateOption, CWD_OPTION_DESCRIPTION, JSON_OPTION_DESCRIPTION, RUN_OPTION_DESCRIPTION, wantsJson, writeResult, humanError, writeHuman, } from "../io.js";
 export function registerFeedbackCommands(parent, io) {
     const feedback = parent
         .command("feedback")
-        .description("Create public-safe feedback drafts without GitHub API mutation.")
-        .summary("Create public-safe feedback drafts, no GitHub API.");
+        .description("Draft public-safe feedback issues from a run. humanish never calls the GitHub API.")
+        .summary("Draft public-safe feedback issues from a run.");
     feedback
         .command("list")
         .description("List recorded feedback candidates and any saved draft.")
-        .addHelpText("after", "\nWith no candidates, feedback draft and feedback issue can generate a run-summary follow-up. Public drafting still requires share_ready verification.\n")
-        .option("--run <id>", "Run id or latest pointer.", "latest")
-        .option("--cwd <path>", "Target project directory.", ".")
+        .addHelpText("after", "\nWith no candidates, feedback draft and feedback issue write a run-summary follow-up for a live run that verifies share_ready. A dry run gets no draft.\n")
+        .option("--run <id>", RUN_OPTION_DESCRIPTION, "latest")
+        .option("--cwd <path>", CWD_OPTION_DESCRIPTION, ".")
         .option("--json", JSON_OPTION_DESCRIPTION)
         .action((options, command) => handleFeedbackList(io, options, command));
     feedback
         .command("draft")
         .description("Generate a public-safe feedback draft from verified evidence.")
-        .option("--run <id>", "Run id or latest pointer.", "latest")
-        .option("--cwd <path>", "Target project directory.", ".")
+        .option("--run <id>", RUN_OPTION_DESCRIPTION, "latest")
+        .option("--cwd <path>", CWD_OPTION_DESCRIPTION, ".")
         .option("--analysis <id>", "Independent analysis version; use with --finding.")
         .option("--finding <id>", "Finding within --analysis, separate from participant candidates.")
         .option("--candidate <id>", "Which finding to draft (ids from `feedback list`); default: the first.")
@@ -27,8 +27,8 @@ export function registerFeedbackCommands(parent, io) {
     feedback
         .command("verify")
         .description("Verify the feedback draft for public issue eligibility.")
-        .option("--run <id>", "Run id or latest pointer.", "latest")
-        .option("--cwd <path>", "Target project directory.", ".")
+        .option("--run <id>", RUN_OPTION_DESCRIPTION, "latest")
+        .option("--cwd <path>", CWD_OPTION_DESCRIPTION, ".")
         .option("--analysis <id>", "Independent analysis version; use with --finding.")
         .option("--finding <id>", "Finding within --analysis, separate from participant candidates.")
         .option("--candidate <id>", "Which finding to verify (ids from `feedback list`); default: the first.")
@@ -37,8 +37,8 @@ export function registerFeedbackCommands(parent, io) {
     feedback
         .command("issue")
         .description("Print Markdown for a public GitHub issue. Does not mutate GitHub.")
-        .option("--run <id>", "Run id or latest pointer.", "latest")
-        .option("--cwd <path>", "Target project directory.", ".")
+        .option("--run <id>", RUN_OPTION_DESCRIPTION, "latest")
+        .option("--cwd <path>", CWD_OPTION_DESCRIPTION, ".")
         .requiredOption("--repo <owner/repo>", "Repository slug used in rendered filing instructions.")
         .option("--format <format>", "Output format.", "markdown")
         .option("--analysis <id>", "Independent analysis version; use with --finding.")
@@ -49,8 +49,8 @@ export function registerFeedbackCommands(parent, io) {
     feedback
         .command("issue-url")
         .description("Print a prefilled public issue URL. Does not mutate GitHub.")
-        .option("--run <id>", "Run id or latest pointer.", "latest")
-        .option("--cwd <path>", "Target project directory.", ".")
+        .option("--run <id>", RUN_OPTION_DESCRIPTION, "latest")
+        .option("--cwd <path>", CWD_OPTION_DESCRIPTION, ".")
         .requiredOption("--repo <owner/repo>", "Repository slug used in the generated URL.")
         .option("--analysis <id>", "Independent analysis version; use with --finding.")
         .option("--finding <id>", "Finding within --analysis, separate from participant candidates.")
@@ -87,7 +87,7 @@ async function handleFeedbackIssue(io, options, command) {
         io.writeOut(result.issueMarkdown);
     }
     else {
-        io.writeErr(formatFeedbackHuman(result));
+        writeHuman(command, io, formatFeedbackHuman(result));
     }
     io.setExitCode(result.ok ? 0 : 2);
 }
@@ -100,14 +100,13 @@ async function handleFeedbackIssueUrl(io, options, command) {
         io.writeOut(`${result.issueUrl}\n`);
     }
     else {
-        io.writeErr(formatFeedbackHuman(result));
+        writeHuman(command, io, formatFeedbackHuman(result));
     }
     io.setExitCode(result.ok ? 0 : 2);
 }
 function formatFeedbackHuman(result) {
-    if (!result.ok) {
-        return `${result.error?.code}: ${result.error?.message}\n`;
-    }
+    if (!result.ok)
+        return humanError(result.error);
     const candidates = result.candidates ?? [];
     const noCandidates = result.candidates !== undefined && candidates.length === 0;
     return ([
@@ -123,11 +122,11 @@ function formatFeedbackHuman(result) {
         ...(noCandidates
             ? [
                 "candidates: none recorded",
-                "With no candidates, feedback draft and feedback issue can generate a run-summary follow-up after share_ready verification.",
+                "With no candidates, feedback draft and feedback issue write a run-summary follow-up for a live run that verifies share_ready.",
                 ...(result.draft ? [`summary: ${result.draft.summary}`] : []),
             ]
             : []),
-        // Every finding the run produced, so the second and third are one flag away (#609).
+        // Every finding the run produced, so the second and third are one flag away.
         ...(candidates.length > 1 || (candidates.length === 1 && result.draft === undefined)
             ? [
                 `candidates (${candidates.length}; choose one with --candidate <id>):`,

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);
+    });
+}

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;