humanish 0.112.0 → 0.114.0

package/dist/cli/commands/runs.js

@@ -1,5 +1,5 @@
 import path from "node:path";
-import { Command, Option } from "commander";
+import { Command, InvalidArgumentError, Option } from "commander";
 import { shellArg } from "../../substrates/shell.js";
 import { computeStats, formatStatsHuman } from "../../run/stats.js";
 import { DEFAULT_EXPORT_MAX_BYTES, exportRun, formatExportHuman } from "../../feedback/export.js";
@@ -8,7 +8,7 @@ import { verifyRun } from "../../verify/verify.js";
 import { reclaimPreflightSandboxes, reclaimRunSandboxes, } from "../../run/reclaim.js";
 import { runDisplay } from "../../run/display.js";
 import { addRunOptions, handleRun } from "./run-command.js";
-import { applyEnvFileOption, CWD_OPTION_DESCRIPTION, DOTENV_OPTION_DESCRIPTION, dotenvPathOf, envFileAliasOption, JSON_OPTION_DESCRIPTION, RUN_OPTION_DESCRIPTION, writeResult, humanError, } from "../io.js";
+import { applyEnvFileOption, CWD_OPTION_DESCRIPTION, DOTENV_OPTION_DESCRIPTION, dotenvPathOf, envFileAliasOption, JSON_OPTION_DESCRIPTION, parsePositiveInteger, RUN_OPTION_DESCRIPTION, writeResult, humanError, } from "../io.js";
 import { plural } from "../../run/text.js";
 import { warnAndQueue } from "../deprecations.js";
 import { formatFindings, readRunFindings } from "../findings.js";
@@ -136,29 +136,52 @@ export function registerRunsCommand(parent, io) {
         io.setExitCode(result.ok ? 0 : 2);
     });
 }
+/** A whole number of GiB or CPUs above zero, for `runtime setup --memory` and `--cpus`. */
+function wholeNumber(flag) {
+    return (value) => {
+        const parsed = parsePositiveInteger(value);
+        if (parsed === null)
+            throw new InvalidArgumentError(`${flag} takes a whole number above zero, such as 8.`);
+        return parsed;
+    };
+}
 export function registerRuntimeCommands(parent, io) {
     const runtime = parent
         .command("runtime")
         .description("Prepare or inspect the local browser runtime.");
     for (const action of ["status", "setup"]) {
-        runtime
+        const command = runtime
             .command(action)
             .description(action === "status"
-            ? "Check local Docker, virtualization and the cached browser image without downloads."
+            ? "Check local Docker, virtualization and the cached browser image without downloads, and how many participant desktops fit."
             : "Download and install the local browser image. Does not start a study or use model quota.")
             .option("--json", JSON_OPTION_DESCRIPTION)
-            .option("--media", "Prepare or inspect the optional camera and speech runtime.")
-            .action(async (_options, command) => {
+            .option("--media", "Prepare or inspect the optional camera and speech runtime.");
+        if (action === "setup")
+            command
+                .option("--memory <GiB>", "Mac only: the humanish Lima VM's memory. Resizes an existing VM, which stops it first.", wholeNumber("--memory"))
+                .option("--cpus <n>", "Mac only: the humanish Lima VM's CPUs. Resizes an existing VM, which stops it first.", wholeNumber("--cpus"));
+        command.action(async (options, command) => {
             const { localRuntimeStatus, prepareLocalRuntime } = await import("../../substrates/local/runtime.js");
+            const { describeCapacity } = await import("../../substrates/local/capacity.js");
+            const media = options.media === true;
             try {
-                if (action === "setup")
+                if (action === "setup") {
+                    const size = {
+                        ...(options.memory === undefined ? {} : { memoryGiB: options.memory }),
+                        ...(options.cpus === undefined ? {} : { cpus: options.cpus }),
+                    };
                     await prepareLocalRuntime({
-                        media: _options.media === true,
+                        media,
+                        ...(Object.keys(size).length === 0 ? {} : { size }),
                         progress: (message) => io.writeErr(`${message}\n`),
                     });
-                const status = await localRuntimeStatus({ media: _options.media === true });
+                }
+                const status = await localRuntimeStatus({ media });
                 const result = { schema: "humanish.runtime-result.v1", ...status };
-                writeResult(command, io, result, () => `${status.message}\n`);
+                writeResult(command, io, result, () => [status.message, ...(status.capacity ? [describeCapacity(status.capacity)] : [])]
+                    .map((line) => `${line}\n`)
+                    .join(""));
                 io.setExitCode(status.ok ? 0 : 2);
             }
             catch (error) {

package/dist/cli/commands/setup.js

@@ -1,5 +1,6 @@
 import { Command } from "commander";
 import { listUserKeys, resolveKeyName, setUserKey, unsetUserKey, userKeyStorePath, } from "../../keys/key-resolution.js";
+import { askForMissingKeys, formatKeyStatus, keyStatus, otherStoredKeys, } from "../../keys/key-status.js";
 import { promptSecret } from "../secret-prompt.js";
 import { runInit } from "../../study/init.js";
 import { buildPayload, disabledByEnvironment, readTelemetryState, telemetryStatePath, writeTelemetryState, } from "../telemetry.js";
@@ -177,20 +178,107 @@ async function readSecretValue(useStdin, promptLabel) {
         const text = Buffer.concat(chunks).toString("utf8").trim();
         return text.length > 0 ? text : null;
     }
-    return promptSecret(promptLabel, process.stdin, process.stderr);
+    // An empty line is no value here: only the walk over missing keys reads it as "skip".
+    return (await promptSecret(promptLabel, process.stdin, process.stderr)) || null;
+}
+/** `humanish keys` and `humanish keys status`: each provider key's source, never a value. */
+async function writeKeyStatus(command, io) {
+    const rows = await keyStatus({ cwd: process.cwd(), env: process.env });
+    const others = otherStoredKeys(process.env);
+    const missing = rows.filter((row) => row.source === null).length;
+    const result = {
+        schema: KEYS_RESULT_SCHEMA,
+        ok: true,
+        action: "status",
+        store: userKeyStorePath(process.env),
+        names: rows.filter((row) => row.source !== null).map((row) => row.name),
+        keys: rows.map(({ name, use, source, hint }) => ({
+            name,
+            use,
+            source,
+            ...(source === null ? { hint } : {}),
+        })),
+        ...(others.length > 0 ? { otherStored: others } : {}),
+        message: missing === 0
+            ? "Every provider key is set."
+            : `${plural(missing, "provider key")} ${missing === 1 ? "is" : "are"} missing.`,
+    };
+    writeResult(command, io, result, () => formatKeyStatus(rows, others));
+    io.setExitCode(0);
+}
+/** "A", "A and B", "A, B and C". */
+function listNames(names) {
+    return names.length < 2 ? names.join("") : `${names.slice(0, -1).join(", ")} and ${names.at(-1)}`;
+}
+/**
+ * `humanish keys set` with no key named. On a terminal it asks for each missing provider key in
+ * turn; without one there is no one to ask, so it refuses and names the --stdin form.
+ */
+async function setMissingKeys(command, io, useStdin) {
+    const store = userKeyStorePath(process.env);
+    const finish = (ok, names, message) => {
+        const result = {
+            schema: KEYS_RESULT_SCHEMA,
+            ok,
+            action: "set",
+            store,
+            names,
+            message,
+        };
+        writeResult(command, io, result, formatKeysHuman);
+        io.setExitCode(ok ? 0 : 2);
+    };
+    if (useStdin || process.stdin.isTTY !== true || process.stderr.isTTY !== true) {
+        finish(false, [], `missing required argument 'vendor-or-name'. Without a terminal humanish cannot ask for each key, so name the key and pipe its value, for example: printf '%s' "$E2B_API_KEY" | ${cli("keys set e2b --stdin")}`);
+        return;
+    }
+    const rows = await keyStatus({ cwd: process.cwd(), env: process.env });
+    const missing = rows.filter((row) => row.source === null).length;
+    if (missing === 0) {
+        finish(true, [], `Every provider key is already set, so there is nothing to ask for. Replace one with \`${cli("keys set <vendor>")}\`.`);
+        return;
+    }
+    io.writeErr(`${plural(missing, "provider key")} ${missing === 1 ? "is" : "are"} missing. Paste each one when asked, or press Enter to skip it.\n`);
+    const outcome = await askForMissingKeys({
+        rows,
+        env: process.env,
+        prompt: (label) => promptSecret(label, process.stdin, process.stderr),
+    });
+    const sentences = [
+        outcome.stored.length > 0
+            ? `Stored ${listNames(outcome.stored)} (0600).`
+            : "Nothing was stored.",
+        ...(outcome.skipped.length > 0 ? [`Skipped ${listNames(outcome.skipped)}.`] : []),
+        ...(outcome.rejected ?? []).map((entry) => `${entry.name} was not stored: ${entry.message}`),
+        ...(outcome.stoppedAt === undefined
+            ? []
+            : [`Stopped at ${outcome.stoppedAt}; the keys after it were not asked for.`]),
+        `\`${cli("keys")}\` shows where each key comes from.`,
+    ];
+    // A cancel is the person's choice, so only a value the store refused fails the command.
+    finish(outcome.rejected === undefined, outcome.stored, sentences.join(" "));
 }
 export function registerKeysCommand(parent, io) {
     const keys = parent
         .command("keys")
-        .description("Manage the humanish user-level key store used by provider-key discovery.")
-        .summary("Store and manage your provider keys.");
+        .description("Show which provider keys are set and where each comes from, and manage the humanish user key store that provider-key discovery reads.")
+        .summary("Check and store your provider keys.");
+    keys
+        .command("status", { isDefault: true })
+        .description("Show each provider key humanish uses: where it comes from, or the command that adds it. Values are never printed.")
+        .option("--json", JSON_OPTION_DESCRIPTION)
+        .action(async (_options, command) => writeKeyStatus(command, io));
     keys
         .command("set")
-        .argument("<vendor-or-name>", "A vendor alias (openai, e2b, anthropic, github, agentmail) or a raw ENV_NAME.")
-        .description("Store one provider key in the user store (0600), prompted with hidden input.")
+        .argument("[vendor-or-name]", "A vendor alias (openai, e2b, anthropic, github, agentmail) or a raw ENV_NAME. Without one, a terminal asks for each missing key in turn.")
+        .description("Store one provider key in the user store (0600), prompted with hidden input. With no key named, ask for each missing key in turn.")
         .option("--stdin", "Read the value from stdin instead of prompting (for agents/pipes).")
         .option("--json", JSON_OPTION_DESCRIPTION)
         .action(async (vendorOrName, options, command) => {
+        if (vendorOrName === undefined) {
+            await setMissingKeys(command, io, options.stdin === true);
+            return;
+        }
         const name = resolveKeyName(vendorOrName);
         const storePath = userKeyStorePath(process.env);
         if (name === null) {
@@ -294,11 +382,12 @@ export function registerKeysCommand(parent, io) {
 function formatDoctorHuman(result) {
     return ([
         `humanish doctor ${result.ok ? "ok" : "needs setup"}`,
+        ...(result.next === undefined ? [] : [`next: ${result.next}`]),
         `cwd: ${result.cwd}`,
         // "missing" is a verdict, and a row that never ran has none. A participant reading doctor on a
         // fresh desktop got `- missing package.json: package.json is present and safe to read`, which
         // contradicts itself in eleven words (labs/tui-self-study.yaml).
-        ...result.checks.map((check) => `- ${check.status.replace("_", " ")} ${check.name}: ${check.message}`),
+        ...result.checks.map((check) => `- ${check.status.replace("_", " ")} ${check.name}: ${check.message.replaceAll("\n", "\n    ")}`),
     ].join("\n") + "\n");
 }
 function formatInitHuman(result) {

package/dist/cli/commands/study-format.js

@@ -1,3 +1,4 @@
+import { participantCaption } from "../../run/participant-caption.js";
 import { formatCuaDiagnostics, formatCuaStopCause } from "../../routes/computer-use/diagnostics.js";
 /** A run's first lines: the command that ran, whether it was a dry run, how it ended, and its route. */
 function runHeader(result, route) {
@@ -39,17 +40,19 @@ export function formatConcurrentSharedWorldStudyHuman(result) {
         ...runHeader(result, "shared-world"),
         `run: ${result.runId}`,
         `actor: ${result.actor}`,
-        `topology: ${result.topology}/${result.topologyMode} (${result.roleCount} persona${result.roleCount === 1 ? "" : "s"}, concurrency ${result.concurrency})`,
+        `participants: ${result.roleCount}, up to ${result.concurrency} at once`,
         ...(result.host ? [`host: ${result.host}`] : []),
         ...(result.subject?.commit
-            ? [`plane: ${result.subject.repo}@${result.subject.commit.slice(0, 12)}`]
+            ? [`app: ${result.subject.repo}@${result.subject.commit.slice(0, 12)}`]
             : []),
         ...(result.overlapProven === undefined
             ? []
             : [
-                `overlap: ${result.overlapProven ? "proven" : "not observed"} (this run only; no scale or adoption claim)`,
+                result.overlapProven
+                    ? "Participants used the app at the same time (observed in this run only)."
+                    : "Participants were not observed using the app at the same time.",
             ]),
-        ...result.roles.map((participant) => `persona ${participant.id} (${participant.persona}): ${participantStatus(participant.status)}${participant.session ? ` (${participant.session.completionReason})` : ""}${participant.ok ? "" : ", not ok"}`),
+        ...result.roles.map((participant) => `${participantCaption({ id: participant.id, personaId: participant.persona })}: ${participantStatus(participant.status)}${participant.ok ? "" : ", not ok"}`),
         ...(result.subjectSandbox
             ? [
                 `subject sandbox: ${sandboxName(result.subjectSandbox)} killed=${result.subjectSandbox.killed ? "yes" : "no"}`,

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

@@ -7,6 +7,7 @@ import { warnAndQueue } from "../deprecations.js";
 import { planStudy, resolveStudyDryRun } from "../../study/plan.js";
 import { keyNamesOf } from "../../study/requirements.js";
 import { routeOf } from "../../study/plan.js";
+import { computerUseParticipantCount } from "../../study/routing.js";
 import { computerUseRouteRun } from "./study-route-computer-use.js";
 import { runRoute } from "./study-route-run.js";
 import { scriptedRouteRun } from "./study-route-scripted.js";
@@ -130,7 +131,7 @@ export async function runStudyCommand(args) {
                 // 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);
+            const analysisBudget = automaticAnalysisBudget(config.review?.analysis, route, computerUseParticipantCount(config));
             if (analysisBudget && resolveStudyDryRun(config, args.options.dryRun, true) === false) {
                 args.io.writeErr(`${formatAutomaticAnalysisBudget(analysisBudget)}\n`);
             }

package/dist/cli/commands/study.js

@@ -140,7 +140,7 @@ function formatStudyCheckHuman(result) {
         ...(result.sandbox.created
             ? [`sandbox: created=yes killed=${result.sandbox.killed === true ? "yes" : "no"}`]
             : []),
-        ...result.checks.map((check) => `- ${check.ok ? "ok" : "fail"} ${check.name}: ${check.message}`),
+        ...result.checks.map((check) => `- ${check.checked === false ? "not checked" : check.ok ? "ok" : "fail"} ${check.name}: ${check.message}`),
         ...result.warnings.map((warning) => `warning: ${warning}`),
     ].join("\n") + "\n";
     return result.error === undefined ? stdout : { stdout, error: result.error };

package/dist/cli/commands/tui.js

@@ -278,7 +278,7 @@ async function storeAgentmailKey(session) {
     const { cwd, runtime, sessionEnv } = session;
     // startTui has unmounted: only the host reads the credential, then remounts the view.
     const value = await runtime.promptSecret("AgentMail API key", runtime.stdin, runtime.stdout);
-    if (value === null)
+    if (value === null || value === "")
         return "Key entry cancelled. Nothing was changed.";
     try {
         setUserKey("AGENTMAIL_API_KEY", value, sessionEnv);

package/dist/cli/doctor.d.ts

@@ -12,6 +12,8 @@ export interface DoctorResult {
     schema: typeof DOCTOR_SCHEMA;
     ok: boolean;
     cwd: string;
+    /** The step to take first, such as preparing a local study's runtime. */
+    next?: string;
     checks: Array<{
         name: string;
         ok: boolean;

package/dist/cli/doctor.js

@@ -11,6 +11,8 @@ import { studySetupChecks, studiesByRequiredKey, } from "../study/doctor.js";
 import { prepareSelectedOutputDirectory, } from "../run/contained-output.js";
 import { implicitProjectDirectoryExists, readImplicitProjectFile, validateCwd, } from "../run/project.js";
 import { cli } from "./invocation.js";
+import { recordedVersion } from "./update-check.js";
+import { CLI_VERSION } from "./version.js";
 const DOCTOR_SCHEMA = "humanish.doctor-result.v1";
 /**
  * Version 2.3.1 stopped holding a launched background command's event stream open. Version 2.3.2
@@ -94,6 +96,7 @@ export async function doctor(cwdInput, options = {}) {
         ...(await projectChecks(projectRoot)),
         await desktopSdkCheck(setup),
         terminalSurfaceCheck(),
+        ...versionCheck(env),
         ...localAgentChecks(agents),
         await claudeTranscriptCheck(env),
         ...keyChecks(probes, receivingKey, setup, keyUsers),
@@ -109,6 +112,7 @@ export async function doctor(cwdInput, options = {}) {
         schema: DOCTOR_SCHEMA,
         ok: checks.every((check) => check.ok),
         cwd,
+        ...(setup?.next === undefined ? {} : { next: setup.next }),
         checks: withStatus(checks),
     };
 }
@@ -246,6 +250,20 @@ function terminalSurfaceCheck() {
         }),
     };
 }
+/** The latest version the update check recorded on this machine; no row before a check. */
+function versionCheck(env) {
+    const recorded = recordedVersion(CLI_VERSION, env, env.HOME ?? homedir());
+    if (recorded === undefined)
+        return [];
+    return [
+        {
+            name: "humanish version",
+            ok: true,
+            ...(recorded.newer ? { status: "note" } : {}),
+            message: recorded.message,
+        },
+    ];
+}
 /** Probes the live-run keys, plus the receiving-email key a real-comms study names. */
 async function probeDoctorKeys(cwd, env, study, keyDeps, dotenv) {
     const keyNames = new Set(["OPENAI_API_KEY", "E2B_API_KEY", "GH_TOKEN", "CODEX_API_KEY"]);

package/dist/cli/findings.js

@@ -2,6 +2,7 @@
 // `humanish.analysis-findings.v1` projection and its text. The analysis artifact stays the record;
 // this reads the version `analyze show` selects and never starts an analysis.
 import path from "node:path";
+import { admittingMaxCost, costRefusalText } from "../analysis/admission.js";
 import { DEFAULT_ANALYSIS_MAX_COST_USD } from "../analysis/automatic-config.js";
 import { loadAnalysis } from "../analysis/load.js";
 import { projectShareCheckedAnalysis } from "../analysis/sharing.js";
@@ -199,9 +200,11 @@ export function analysisFindings(source) {
         const outcome = analysisOutcomeText(job);
         return withoutFindings(source, "failed", job.reason, `The automatic analysis ${outcome.startsWith("failed") ? "" : "was "}${outcome}.`, analyzeCommand(source, job.reason === "AUTOMATIC_ANALYSIS_CODEX_UNAVAILABLE" ? "codex" : undefined));
     }
+    if (job?.state === "skipped" && job.admission)
+        return withoutFindings(source, "skipped", job.reason, `The automatic analysis was refused before it started. ${costRefusalText(job.admission)}`, cli(`analyze --run ${source.runId}${source.cwdFlag} --max-cost ${admittingMaxCost(job.admission)}`));
     if (job?.state === "skipped") {
         const refused = job.reason === "AUTOMATIC_ANALYSIS_ADMISSION_REFUSED";
-        return withoutFindings(source, "skipped", job.reason, `The automatic analysis was ${analysisOutcomeText(job)}.${refused ? " The dry run prints its cost estimate; run it again with a --max-cost above the estimate." : ""}`, job.reason === "AUTOMATIC_ANALYSIS_NO_PARTICIPANT_EVIDENCE"
+        return withoutFindings(source, "skipped", job.reason, `The automatic analysis was ${analysisOutcomeText(job)}.${refused ? " The dry run says why, and for a cost refusal names the --max-cost that admits it." : ""}`, job.reason === "AUTOMATIC_ANALYSIS_NO_PARTICIPANT_EVIDENCE"
             ? null
             : `${analyzeCommand(source, undefined)}${refused ? " --dry-run" : ""}`);
     }

package/dist/cli/io.d.ts

@@ -1,6 +1,7 @@
 import { Command, Option } from "commander";
 import { discoverProviderKeys, type DotenvLoad } from "../keys/key-resolution.js";
 import { type TelemetryProperties } from "./telemetry.js";
+import type { UpdateCheckContext } from "./update-check.js";
 import type { RunResult } from "../run/results.js";
 export declare const CLI_RESPONSE_SCHEMA = "humanish.cli-response.v1";
 export { CLI_VERSION } from "./version.js";
@@ -9,6 +10,7 @@ export interface CliIo {
     writeErr(text: string): void;
     setExitCode(code: number): void;
     keyDiscovery?: typeof discoverProviderKeys;
+    updateCheck?: Partial<UpdateCheckContext>;
 }
 export declare const JSON_OPTION_DESCRIPTION = "Print a machine-readable JSON response.";
 export declare const CWD_OPTION_DESCRIPTION = "Project directory.";
@@ -136,4 +138,5 @@ export declare function analysisOutcomeText(analysis: {
     state: string;
     reason: string | null;
 }): string;
+/** Preserve the run's own result while making requested post-processing failures machine-visible. */
 export declare function automaticAnalysisEnvelope<T>(result: T): T;

package/dist/cli/io.js

@@ -1,5 +1,5 @@
-import { automaticAnalysisSucceeded, defaultAnalysisOverBudget, } from "../analysis/automatic-completion.js";
-import { DEFAULT_ANALYSIS_MAX_COST_USD } from "../analysis/automatic-config.js";
+import { automaticAnalysisSucceeded, } from "../analysis/automatic-completion.js";
+import { admittingMaxCost, costRefusalText, refusedCost, } from "../analysis/admission.js";
 import { Command, Option } from "commander";
 import { loadEnvFile, recordDotenvNames } from "../keys/env-file.js";
 import { discoverProviderKeys } from "../keys/key-resolution.js";
@@ -188,13 +188,14 @@ export function writeResult(command, io, result, formatHuman) {
         writeHuman(command, io, formatHuman(output));
         if (output !== null && typeof output === "object" && "automaticAnalysis" in output) {
             const analysis = output.automaticAnalysis;
-            if (analysis)
+            const cost = analysis?.result?.admission && refusedCost(analysis.result.admission);
+            if (cost)
+                io.writeOut(`analysis: refused before it started. ${refusedAnalysisText(cost, analysis.result?.run ?? "latest")}\n`);
+            else if (analysis)
                 io.writeOut(`analysis: ${analysisOutcomeText(analysis)}\n`);
             const rejected = analysis?.result?.rejectedOutputPath;
             if (rejected)
                 io.writeOut(`analysis: ${analysis.result?.error?.code ?? "rejected"}; the rejected output is kept locally at ${rejected}\n`);
-            if (defaultAnalysisOverBudget(output))
-                io.writeOut(overBudgetAnalysisHint(output));
         }
     }
     markInvocationEnvelopeWritten(command);
@@ -286,7 +287,7 @@ const ANALYSIS_REASON_TEXT = {
     AUTOMATIC_ANALYSIS_SOURCE_UNAVAILABLE: "skipped because the run's evidence could not be read",
     AUTOMATIC_ANALYSIS_ALREADY_REQUESTED: "skipped because this run's analysis was already requested",
     AUTOMATIC_ANALYSIS_BUSY: "skipped because another analysis is running",
-    AUTOMATIC_ANALYSIS_ADMISSION_REFUSED: "not started because its configuration or question was refused",
+    AUTOMATIC_ANALYSIS_ADMISSION_REFUSED: "refused before it started: its configuration, question, evidence or cost did not pass admission",
     AUTOMATIC_ANALYSIS_CLEANUP_UNCONFIRMED: "not started because the run's cleanup was not confirmed",
     AUTOMATIC_ANALYSIS_REUSED: "complete, reusing an earlier analysis of the same evidence",
     AUTOMATIC_ANALYSIS_LIMITATIONS: "partial, because it covered only part of the evidence",
@@ -305,13 +306,11 @@ export function analysisOutcomeText(analysis) {
         return analysis.state;
     return ANALYSIS_REASON_TEXT[analysis.reason] ?? `${analysis.state} (${analysis.reason})`;
 }
-/** Preserve the run's own result while making requested post-processing failures machine-visible. */
-function overBudgetAnalysisHint(result) {
-    const estimate = result.automaticAnalysis?.result?.admission?.estimatedCostUsd ?? null;
-    const suggested = Math.ceil(estimate ?? DEFAULT_ANALYSIS_MAX_COST_USD + 1);
-    const shown = estimate === null ? "" : ` ($${estimate.toFixed(2)})`;
-    return `analysis: its estimate${shown} is over the default $${DEFAULT_ANALYSIS_MAX_COST_USD} cap, so no request was sent. To analyze this run: ${cli(`analyze --run ${result.runId ?? "latest"} --max-cost ${suggested}`)}\n`;
+/** What a refused analysis would cost and the command that runs it with a cap that admits it. */
+function refusedAnalysisText(cost, runId) {
+    return `${costRefusalText(cost)} To run it, raise the cap: ${cli(`analyze --run ${runId} --max-cost ${admittingMaxCost(cost)}`)}`;
 }
+/** Preserve the run's own result while making requested post-processing failures machine-visible. */
 export function automaticAnalysisEnvelope(result) {
     if (result === null ||
         typeof result !== "object" ||

package/dist/cli/program.js

@@ -2,16 +2,18 @@ import { readFileSync } from "node:fs";
 import { formatOrientationHuman, readOrientation } from "./orientation.js";
 import { dirname } from "node:path";
 import { fileURLToPath } from "node:url";
-import { Command } from "commander";
+import { Command, Help } from "commander";
 import { redactText } from "../evidence/redaction.js";
 import { PortInUseError } from "../observer/listen.js";
 import { buildPayload, disabledByEnvironment, durationBucket, readTelemetryState, sendTelemetry, TELEMETRY_NOTICE, writeTelemetryState, isOwnCheckoutRun, } from "./telemetry.js";
+import { checkForUpdate, startRefreshWorker } from "./update-check.js";
 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 { registerStudyCommands } from "./commands/study.js";
 import { registerMigrateCommand } from "./commands/migrate.js";
+import { registerNotesCommand } from "./commands/notes.js";
 import { registerObserveCommand } 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";
@@ -95,6 +97,29 @@ async function recordCommandTelemetry(command, ok, durationMs, exitCode) {
         // Metrics are our problem, never the operator's.
     }
 }
+/**
+ * After a command, one line on stderr when a newer humanish is published. It reads only the cache;
+ * the registry request runs detached (see update-check.ts), so nothing here waits on the network.
+ */
+function noticeNewerVersion(command, io) {
+    try {
+        const notice = checkForUpdate({
+            installed: CLI_VERSION,
+            env: process.env,
+            terminal: process.stderr.isTTY === true,
+            json: wantsJson(command),
+            ownCheckout: isOwnCheckoutRun(process.cwd(), dirname(fileURLToPath(import.meta.url)), (p) => readFileSync(p, "utf8")),
+            now: Date.now(),
+            startRefresh: startRefreshWorker,
+            ...io.updateCheck,
+        });
+        if (notice !== undefined)
+            io.writeErr(`${notice}\n`);
+    }
+    catch {
+        // An update notice is never a reason for a command to fail.
+    }
+}
 /**
  * HUMANISH_DEBUG_HANDLES=1: after a command's handler settles, name what is still keeping the
  * process alive. A live terminal run wrote its result 64 s in and the CLI stayed up for
@@ -165,6 +190,7 @@ class HumanishCommand extends Command {
             const noticed = announceTelemetryOnce(this, cliIo);
             const finish = (ok) => {
                 void recordCommandTelemetry(this, ok, Date.now() - startedAt, lastExitCode);
+                noticeNewerVersion(this, cliIo);
                 reportActiveHandles(this, cliIo);
             };
             try {
@@ -326,6 +352,15 @@ export function createProgram(io = {}) {
         // each subcommand when it is created.
         .helpOption("-h, --help", "Show help for this command.")
         .helpCommand("help [command]", "Show help for a command.")
+        // `help <command>` and `<command> help` keep working; a command's listing names only the
+        // commands that do something, so `help` is left out of every Commands section.
+        .configureHelp({
+        visibleCommands(command) {
+            return Help.prototype.visibleCommands
+                .call(this, command)
+                .filter((child) => child.name() !== "help");
+        },
+    })
         .showHelpAfterError()
         .option("--json", "Print machine-readable JSON responses where supported.")
         .configureOutput({
@@ -358,6 +393,7 @@ export function createProgram(io = {}) {
     registerVerifyCommand(program, cliIo);
     registerReviewCommand(program, cliIo);
     registerAnalyzeCommand(program, cliIo);
+    registerNotesCommand(program, cliIo);
     registerFeedbackCommands(program, cliIo);
     registerExportCommand(program, cliIo);
     registerRunsCommand(program, cliIo);

package/dist/cli/secret-prompt.d.ts

@@ -1,2 +1,6 @@
-/** Host-owned entry: no secret crosses the TUI view contract or reaches a writable terminal. */
+/**
+ * Host-owned entry: no secret crosses the TUI view contract or reaches a writable terminal.
+ * Resolves to the trimmed line, an empty string when Enter was pressed alone, or null when the
+ * person cancelled or there is no terminal.
+ */
 export declare function promptSecret(label: string, stdin: NodeJS.ReadStream, stdout: NodeJS.WriteStream): Promise<string | null>;

package/dist/cli/secret-prompt.js

@@ -1,6 +1,10 @@
 import { createInterface } from "node:readline/promises";
 import { Writable } from "node:stream";
-/** Host-owned entry: no secret crosses the TUI view contract or reaches a writable terminal. */
+/**
+ * Host-owned entry: no secret crosses the TUI view contract or reaches a writable terminal.
+ * Resolves to the trimmed line, an empty string when Enter was pressed alone, or null when the
+ * person cancelled or there is no terminal.
+ */
 export async function promptSecret(label, stdin, stdout) {
     if (!stdin.isTTY || !stdout.isTTY)
         return null;
@@ -27,7 +31,7 @@ export async function promptSecret(label, stdin, stdout) {
             stdout.write("\n");
             resolve(value);
         };
-        reader.once("line", (line) => finish(line.trim() || null));
+        reader.once("line", (line) => finish(line.trim()));
         reader.once("SIGINT", () => finish(null));
         reader.once("close", () => finish(null));
         reader.once("error", () => finish(null));

package/dist/cli/update-check-worker.d.ts

@@ -0,0 +1 @@
+export {};

package/dist/cli/update-check-worker.js

@@ -0,0 +1,5 @@
+// Started detached by startRefreshWorker in update-check.ts, with the cache path as its argument.
+import { refreshUpdateCache } from "./update-check.js";
+const cachePath = process.argv[2];
+if (cachePath !== undefined)
+    await refreshUpdateCache({ cachePath });

package/dist/cli/update-check.d.ts

@@ -0,0 +1,46 @@
+export interface UpdateCheckContext {
+    /** The running CLI's version. */
+    installed: string;
+    env: NodeJS.ProcessEnv;
+    /** Whether stderr is a terminal. */
+    terminal: boolean;
+    /** Whether the command prints a JSON document. */
+    json: boolean;
+    /** Whether this CLI runs from humanish's own source checkout. */
+    ownCheckout: boolean;
+    /** The clock, in epoch milliseconds. */
+    now: number;
+    home?: string;
+    /** Starts the background registry request that writes the cache. Never awaited. */
+    startRefresh: (cachePath: string) => void;
+}
+/**
+ * The one line to print after a command when the cache names a newer humanish, at most once a day.
+ * Records that it was shown. Every failure inside is swallowed: an update notice is never a reason
+ * for a command to fail.
+ */
+export declare function checkForUpdate(context: UpdateCheckContext): string | undefined;
+/**
+ * The version the last successful check recorded, compared with `installed`, for `doctor`. Reads the
+ * cache only; undefined until a check has succeeded on this machine.
+ */
+export declare function recordedVersion(installed: string, env: NodeJS.ProcessEnv, home?: string): {
+    newer: boolean;
+    message: string;
+} | undefined;
+/**
+ * Ask the npm registry for humanish's `latest` dist-tag and record it in the cache. The detached
+ * worker runs this. The request is a GET with an Accept header and nothing else: no machine id,
+ * installed version, command or path. A failed or malformed answer leaves the cache as it was.
+ */
+export declare function refreshUpdateCache(args: {
+    cachePath: string;
+    fetchFn?: (url: string, init: RequestInit) => Promise<Response>;
+    now?: () => number;
+    timeoutMs?: number;
+}): Promise<void>;
+/**
+ * Start the worker that runs refreshUpdateCache, detached and unreferenced so this process exits
+ * without waiting for it. A source checkout has no built worker, and nothing starts.
+ */
+export declare function startRefreshWorker(cachePath: string): void;