humanish 0.111.4 → 0.113.0

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.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.d.ts

@@ -4,14 +4,13 @@ import type { AnalysisArtifact, LoadedAnalysis } from "../analysis/types.js";
 import { type CliIo } from "./io.js";
 export declare const ANALYSIS_FINDINGS_SCHEMA = "humanish.analysis-findings.v1";
 type Finding = NonNullable<AnalysisArtifact["result"]>["findings"][number];
+type DesignFinding = NonNullable<NonNullable<AnalysisArtifact["result"]>["designFindings"]>[number];
 /** `ready` and `stale` carry findings; every other state carries none and says why in `message`. */
 type FindingsState = "ready" | "stale" | "running" | "none" | "skipped" | "failed" | "dry_run" | "unavailable";
-interface FindingEvidence {
+interface CitedEvidence {
     id: string;
     streamId: string;
     kind: string;
-    /** How the finding's observations used this item: visual, action, participant_statement, inference. */
-    bases: string[];
     /** Index of the latest retained capture at this item, from 0; null before any capture. */
     frame: number | null;
     /** Time since the first retained capture, not a video offset. */
@@ -20,8 +19,19 @@ interface FindingEvidence {
     /** The capture file relative to the project directory, or null for nonvisual evidence. */
     capture: string | null;
 }
+interface FindingEvidence extends CitedEvidence {
+    /** How the finding's observations used this item: visual, action, participant_statement, inference. */
+    bases: string[];
+}
 interface FindingView {
     id: string;
+    /**
+     * One plain sentence about what happened, and one to three about what the person tried and what
+     * got in the way. Null in analyses written before them. An amended finding keeps the original
+     * text here; `correction.replacementClaim` replaces both.
+     */
+    headline: string | null;
+    experience: string | null;
     title: string;
     summary: string;
     impact: Finding["impact"];
@@ -41,6 +51,22 @@ interface FindingView {
         replacementClaim: string | null;
     } | null;
 }
+interface DesignFindingView {
+    id: string;
+    headline: string;
+    screen: string;
+    notice: string;
+    whyItMatters: string;
+    suggestion: string;
+    severity: DesignFinding["severity"];
+    confidence: DesignFinding["confidence"];
+    seenBy: {
+        streamId: string;
+        label: string;
+    }[];
+    /** Each cited item once; at least one has a capture. */
+    evidence: CitedEvidence[];
+}
 export interface AnalysisFindings {
     schema: typeof ANALYSIS_FINDINGS_SCHEMA;
     runId: string;
@@ -66,6 +92,11 @@ export interface AnalysisFindings {
     summary: string | null;
     /** Highest priority first, as the analysis ranked them. */
     findings: FindingView[];
+    /**
+     * Problems a designer would see in the captures, most severe first. Null when the view carries
+     * no analysis result, or the analysis was written before design findings.
+     */
+    designFindings: DesignFindingView[] | null;
     limitations: string[];
     warnings: string[];
 }

package/dist/cli/findings.js

@@ -27,16 +27,10 @@ function analyzeCommand(source, provider) {
         ? `${run} --provider codex`
         : `${run} --max-cost ${DEFAULT_ANALYSIS_MAX_COST_USD}`;
 }
-function evidenceOf(finding, analysis, runRoot) {
-    const bases = new Map();
-    for (const observation of finding.observations)
-        for (const id of observation.evidenceIds) {
-            const set = bases.get(id) ?? new Set();
-            set.add(observation.basis);
-            bases.set(id, set);
-        }
+/** The cited items the analysis evidence resolves, each once, in citation order. */
+function citedEvidence(ids, analysis, runRoot) {
     const byId = new Map(analysis.evidence.map((entry) => [entry.id, entry]));
-    return [...bases].flatMap(([id, used]) => {
+    return [...new Set(ids)].flatMap((id) => {
         const entry = byId.get(id);
         if (!entry)
             return [];
@@ -45,7 +39,6 @@ function evidenceOf(finding, analysis, runRoot) {
                 id,
                 streamId: entry.streamId,
                 kind: entry.kind,
-                bases: [...used],
                 frame: entry.frame,
                 elapsedMs: entry.elapsedMs,
                 at: entry.at,
@@ -54,11 +47,58 @@ function evidenceOf(finding, analysis, runRoot) {
         ];
     });
 }
+function evidenceOf(finding, analysis, runRoot) {
+    const bases = new Map();
+    for (const observation of finding.observations)
+        for (const id of observation.evidenceIds) {
+            const set = bases.get(id) ?? new Set();
+            set.add(observation.basis);
+            bases.set(id, set);
+        }
+    return citedEvidence(bases.keys(), analysis, runRoot).map(({ id, streamId, kind, ...entry }) => ({
+        id,
+        streamId,
+        kind,
+        bases: [...bases.get(id)],
+        ...entry,
+    }));
+}
+const SEVERITY_RANK = {
+    major: 0,
+    moderate: 1,
+    minor: 2,
+};
+/** Most severe first; equal severity keeps the analysis order. */
+function designFindingViews(analysis, runRoot) {
+    const designFindings = analysis.result?.designFindings;
+    if (designFindings === undefined)
+        return null;
+    const labels = new Map(analysis.participants.map((p) => [p.streamId, p.label]));
+    return [...designFindings]
+        .sort((a, b) => SEVERITY_RANK[a.severity] - SEVERITY_RANK[b.severity])
+        .map((finding) => ({
+        id: finding.id,
+        headline: finding.headline,
+        screen: finding.screen,
+        notice: finding.notice,
+        whyItMatters: finding.whyItMatters,
+        suggestion: finding.suggestion,
+        severity: finding.severity,
+        confidence: finding.confidence,
+        seenBy: finding.seenByStreamIds.map((streamId) => ({
+            streamId,
+            label: labels.get(streamId) ?? streamId,
+        })),
+        evidence: citedEvidence(finding.evidenceIds, analysis, runRoot),
+    }));
+}
 function findingView(finding, loaded, runRoot) {
     const labels = new Map(loaded.analysis.participants.map((p) => [p.streamId, p.label]));
     const correction = loaded.corrections.filter((entry) => entry.findingId === finding.id).at(-1);
     return {
         id: finding.id,
+        headline: finding.headline ?? null,
+        experience: finding.experience ?? null,
         title: finding.title,
         summary: finding.summary,
         impact: finding.impact,
@@ -99,6 +139,7 @@ function withoutFindings(source, state, reason, message, next) {
         path: null,
         summary: null,
         findings: [],
+        designFindings: null,
         limitations: [],
         warnings: source.loaded.warnings,
     };
@@ -142,6 +183,7 @@ export function analysisFindings(source) {
             path: path.join(source.runRoot, "analysis", analysis.id, "analysis.json"),
             summary: result.summary,
             findings: result.findings.map((finding) => findingView(finding, { ...loaded, analysis }, source.runRoot)),
+            designFindings: designFindingViews(analysis, source.runRoot),
             limitations: result.limitations,
             warnings: loaded.warnings,
         };
@@ -288,20 +330,49 @@ function momentsText(evidence) {
         parts.push(`${plural(unframed, "item")} with no frame`);
     return parts.join(", ");
 }
+/** The capture files, relative to the run directory, in frame order. */
+function captureFiles(evidence, runRoot) {
+    return [
+        ...new Set(evidence
+            .filter((entry) => entry.capture !== null)
+            .sort((a, b) => (a.frame ?? 0) - (b.frame ?? 0))
+            .map((entry) => (runRoot ? path.relative(runRoot, entry.capture) : entry.capture))),
+    ];
+}
+/**
+ * What a reader sees first: the headline, or the reviewer's claim when a review amended the finding,
+ * since the headline and experience describe the claim it replaced. Null before headlines existed.
+ */
+function leadOf(finding) {
+    const amended = finding.correction?.status === "amended" ? finding.correction : null;
+    if (finding.headline === null)
+        return null;
+    return amended?.replacementClaim
+        ? { headline: amended.replacementClaim, corrected: true }
+        : { headline: finding.headline, corrected: false };
+}
 function findingLines(finding, runRoot) {
     const cited = [...new Set(finding.evidence.map((entry) => entry.streamId))];
     const labels = new Map(finding.affected.map((p) => [p.streamId, p.label]));
     const affectedIds = finding.affected.map((p) => p.streamId);
     const streams = [...affectedIds, ...cited.filter((id) => !labels.has(id))];
-    const captures = [
-        ...new Set(finding.evidence
-            .filter((entry) => entry.capture !== null)
-            .sort((a, b) => (a.frame ?? 0) - (b.frame ?? 0))
-            .map((entry) => (runRoot ? path.relative(runRoot, entry.capture) : entry.capture))),
-    ];
+    const captures = captureFiles(finding.evidence, runRoot);
     const correction = finding.correction;
+    const lead = leadOf(finding);
     return [
-        `${finding.id} ${finding.title}`,
+        ...(lead === null
+            ? [`${finding.id} ${finding.title}`]
+            : [
+                `${finding.id} ${lead.headline}`,
+                ...(lead.corrected
+                    ? [
+                        "   Corrected in human review. The reviewer's claim replaces the original headline and account.",
+                    ]
+                    : finding.experience === null
+                        ? []
+                        : [`   ${finding.experience}`]),
+                `   evidence: ${finding.title}`,
+            ]),
         `   impact: ${IMPACT_TEXT[finding.impact]} · confidence: ${finding.confidence} · recovery: ${RECOVERY_TEXT[finding.recovery]}`,
         `   ${finding.summary}`,
         `   affected: ${finding.affected.length} of ${plural(finding.exposedCount, "exposed participant")}`,
@@ -319,6 +390,34 @@ function findingLines(finding, runRoot) {
             ]),
     ];
 }
+function designFindingLines(finding, runRoot) {
+    const captures = captureFiles(finding.evidence, runRoot);
+    return [
+        `${finding.id} ${finding.severity}: ${finding.headline}`,
+        `   screen: ${finding.screen}`,
+        `   notice: ${finding.notice}`,
+        `   why it matters: ${finding.whyItMatters}`,
+        `   suggestion: ${finding.suggestion}`,
+        `   seen by: ${finding.seenBy.map((p) => p.label).join(", ")} · confidence: ${finding.confidence}`,
+        ...(captures.length === 0 ? [] : [`   captures: ${captures.join(", ")}`]),
+    ];
+}
+/** Nothing for an analysis written before design findings. */
+function designSection(view) {
+    const design = view.designFindings;
+    if (design === null)
+        return [];
+    if (design.length === 0)
+        return ["", "design findings: none in the reviewed captures"];
+    return [
+        "",
+        `design findings: ${design.length}, most severe first`,
+        ...design.flatMap((finding, index) => [
+            ...(index === 0 ? [] : [""]),
+            ...designFindingLines(finding, view.runPath ?? ""),
+        ]),
+    ];
+}
 /** The full findings block: the analysis, every finding with its evidence, and its limitations. */
 export function formatFindings(view) {
     if (view.state !== "ready" && view.state !== "stale")
@@ -330,6 +429,7 @@ export function formatFindings(view) {
         ...(view.state === "stale" ? [`warning: ${view.message}`, `next: ${view.next}`] : []),
         ...(view.summary ? [view.summary] : []),
         ...view.findings.flatMap((finding) => ["", ...findingLines(finding, view.runPath ?? "")]),
+        ...designSection(view),
         ...(view.limitations.length === 0
             ? []
             : ["", "limitations:", ...view.limitations.map((limitation) => `- ${limitation}`)]),
@@ -343,12 +443,30 @@ export function formatFindingsSummary(view, fullCommand, limit = 3) {
     if (view.state !== "ready" && view.state !== "stale")
         return [`findings: ${view.message}`, ...(view.next ? [`next: ${view.next}`] : [])];
     const shown = view.findings.slice(0, limit);
+    const design = view.designFindings;
     return [
         `findings: ${view.findings.length === 0 ? "none" : view.findings.length}${view.state === "stale" ? " (stale)" : ""}`,
-        ...shown.map((finding) => `- ${finding.id} ${IMPACT_TEXT[finding.impact]}, ${finding.confidence} confidence, ${RECOVERY_TEXT[finding.recovery]}: ${finding.title}`),
+        ...shown.map((finding) => {
+            const qualities = `${IMPACT_TEXT[finding.impact]}, ${finding.confidence} confidence, ${RECOVERY_TEXT[finding.recovery]}`;
+            const lead = leadOf(finding);
+            if (lead === null)
+                return `- ${finding.id} ${qualities}: ${finding.title}`;
+            return `- ${finding.id} ${lead.headline} (${lead.corrected ? "corrected in human review" : qualities})`;
+        }),
         ...(view.findings.length > limit
             ? [`- and ${plural(view.findings.length - limit, "more finding")}`]
             : []),
+        ...(design === null
+            ? []
+            : [
+                `design findings: ${design.length === 0 ? "none" : design.length}`,
+                ...design
+                    .slice(0, limit)
+                    .map((finding) => `- ${finding.id} ${finding.severity}: ${finding.headline}`),
+                ...(design.length > limit
+                    ? [`- and ${plural(design.length - limit, "more design finding")}`]
+                    : []),
+            ]),
         `all findings: ${fullCommand}`,
     ];
 }

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.";
@@ -18,7 +20,8 @@ export declare const DOTENV_OPTION_DESCRIPTION = "Load unset variables from this
  * The hidden `--env-file <path>` that `--dotenv` replaced. Node scans the whole argv for
  * `--env-file` before a script runs, and stops only at `--` (src/node_dotenv.cc), so a missing file
  * exits 9 through Node and never reaches humanish. `--dotenv` does not collide.
- * Removed in 0.112.0: deprecated in 0.110.0 on 2026-10-03, it stays 30 days and one minor release.
+ * Removed in the first minor release on or after 2026-11-03: deprecated in 0.110.0 on 2026-10-03, it stays at least 30 days and one
+ * minor release.
  */
 export declare function envFileAliasOption(): Option;
 /** The dotenv path a command was given: `--dotenv`, or the `--env-file` alias with its warning. */

package/dist/cli/io.js

@@ -15,12 +15,13 @@ export const JSON_OPTION_DESCRIPTION = "Print a machine-readable JSON response."
 export const CWD_OPTION_DESCRIPTION = "Project directory.";
 export const RUN_OPTION_DESCRIPTION = "Run id, or latest.";
 export const DOTENV_OPTION_DESCRIPTION = "Load unset variables from this dotenv file. Values are never printed or saved.";
-const ENV_FILE_RENAMED = "`--env-file` is now `--dotenv`; `--env-file` is removed in 0.112.0.";
+const ENV_FILE_RENAMED = "`--env-file` is now `--dotenv`; `--env-file` is removed in the first minor release on or after 2026-11-03.";
 /**
  * The hidden `--env-file <path>` that `--dotenv` replaced. Node scans the whole argv for
  * `--env-file` before a script runs, and stops only at `--` (src/node_dotenv.cc), so a missing file
  * exits 9 through Node and never reaches humanish. `--dotenv` does not collide.
- * Removed in 0.112.0: deprecated in 0.110.0 on 2026-10-03, it stays 30 days and one minor release.
+ * Removed in the first minor release on or after 2026-11-03: deprecated in 0.110.0 on 2026-10-03, it stays at least 30 days and one
+ * minor release.
  */
 export function envFileAliasOption() {
     return new Option("--env-file <path>").hideHelp().conflicts("dotenv");

package/dist/cli/program.js

@@ -2,10 +2,11 @@ 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";
@@ -95,6 +96,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 +189,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 +351,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({

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>;