humanish 0.114.0 → 0.116.0

package/dist/analysis/execute.js

@@ -145,6 +145,7 @@ export function estimateAnalysisAdmission(input, config) {
         outputTokenAllowance: 0,
         estimatedCostUsd: null,
         worstCaseCostUsd: null,
+        admittedCostUsd: null,
         maxCostUsd: null,
         ratesAsOf: null,
     });
@@ -178,6 +179,7 @@ export function estimateAnalysisAdmission(input, config) {
             outputTokenAllowance: null,
             estimatedCostUsd: null,
             worstCaseCostUsd: null,
+            admittedCostUsd: null,
             maxCostUsd: null,
             ratesAsOf: null,
         };
@@ -207,6 +209,7 @@ export function estimateAnalysisAdmission(input, config) {
         outputTokenAllowance: config.maxOutputTokens,
         estimatedCostUsd: cost.expectedCostUsd,
         worstCaseCostUsd: cost.worstCaseCostUsd,
+        admittedCostUsd: cost.admittedCostUsd,
         maxCostUsd: config.maxCostUsd,
         ratesAsOf: rate.asOf,
     };

package/dist/analysis/finding-lead.d.ts

@@ -0,0 +1,27 @@
+import type { AnalysisCorrection, AnalysisResult } from "./types.js";
+type Severity = NonNullable<AnalysisResult["designFindings"]>[number]["severity"];
+export interface FindingLead {
+    /** The reviewer's amended claim, or the plain headline. */
+    headline: string;
+    /**
+     * The line under the headline: the plain experience, or after an amendment a sentence saying the
+     * reviewer's claim replaced the headline and account. Null when the analysis wrote no experience.
+     */
+    account: string | null;
+    /** The headline is a reviewer's amended claim. */
+    corrected: boolean;
+}
+/**
+ * The headline and account a finding leads with, given its latest human review note. An amendment
+ * replaces both, since they describe the claim the reviewer replaced. Null for an analysis written
+ * before headlines, which leads with the finding's title.
+ */
+export declare function findingLead(finding: {
+    headline?: string | null;
+    experience?: string | null;
+}, correction: Pick<AnalysisCorrection, "status" | "replacementClaim"> | null | undefined): FindingLead | null;
+/** Design findings most severe first, in a new array; equal severity keeps the analysis order. */
+export declare function bySeverity<T extends {
+    severity: Severity;
+}>(findings: readonly T[]): T[];
+export {};

package/dist/analysis/finding-lead.js

@@ -0,0 +1,23 @@
+// How a finding opens for a reader, the same in `review`, a feedback draft and the Observer. The
+// Observer bundles this module, so it imports types only (observer/tests/contract-lock.test.ts).
+/**
+ * The headline and account a finding leads with, given its latest human review note. An amendment
+ * replaces both, since they describe the claim the reviewer replaced. Null for an analysis written
+ * before headlines, which leads with the finding's title.
+ */
+export function findingLead(finding, correction) {
+    if (finding.headline === undefined || finding.headline === null)
+        return null;
+    if (correction?.status === "amended" && correction.replacementClaim)
+        return {
+            headline: correction.replacementClaim,
+            account: "Corrected in human review. The reviewer's claim replaces the original headline and account.",
+            corrected: true,
+        };
+    return { headline: finding.headline, account: finding.experience ?? null, corrected: false };
+}
+const SEVERITY_ORDER = ["major", "moderate", "minor"];
+/** Design findings most severe first, in a new array; equal severity keeps the analysis order. */
+export function bySeverity(findings) {
+    return findings.toSorted((a, b) => SEVERITY_ORDER.indexOf(a.severity) - SEVERITY_ORDER.indexOf(b.severity));
+}

package/dist/analysis/service.js

@@ -17,7 +17,8 @@ import { appendAnalysisCorrection, assertAnalysisPublicationCapacity, listAnalys
 import { beginAnalysisExecution, writeAnalysisExecutionReceipt } from "./store-executions.js";
 import { keepRejectedAnalysisOutput } from "./diagnostics.js";
 import { loadAnalysis } from "./load.js";
-import { admittingMaxCost, costRefusalText, refusedCost } from "./admission.js";
+import { costRefusal, refusedCost } from "./admission.js";
+import { cli } from "../cli/invocation.js";
 import { hashAnalysisValue } from "./validation.js";
 import { ANALYSIS_CORRECTION_SCHEMA, } from "./types.js";
 import { RUN_BUNDLE_FILE } from "../run/bundle.js";
@@ -191,13 +192,14 @@ function analyzeConfigRefusal(config) {
 function admissionOnlyResult(base, config) {
     if (!base.admission.allowed) {
         const cost = refusedCost(base.admission);
+        const refusal = cost && costRefusal(cost, `--run ${base.run}`, cli);
         return {
             ...base,
             ok: false,
             error: {
                 code: base.admission.error ?? "analysis_admission_denied",
-                message: cost
-                    ? `${costRefusalText(cost)} To run it, raise the cap: humanish analyze --run ${base.run} --max-cost ${admittingMaxCost(cost)}`
+                message: refusal
+                    ? `${refusal.text} ${refusal.command}`
                     : "The analysis input or configuration did not pass admission. No provider request was sent.",
             },
         };

package/dist/analysis/validation.js

@@ -2,12 +2,13 @@ import { validStoredCodexAnalysisConfig } from "./codex-config.js";
 import { createHash } from "node:crypto";
 import { z } from "zod";
 import { ACTOR_STATUSES, ACTOR_STOP_CAUSES } from "../actors/contract.js";
+import { ANALYSIS_LIMITS, hasControlCharacter, hasRevisionFields } from "./analysis-limits.js";
 import { SHA256_HEX_PATTERN, ACTION_CAPTURE_VERSION, ANALYSIS_SCHEMA, ANALYSIS_CORRECTION_SCHEMA, } from "./types.js";
 const text = (max) => z
     .string()
     .max(max)
-    .refine((value) => !/[\x00-\x08\x0b\x0c\x0e-\x1f\x7f]/.test(value), "Invalid text.");
-const label = text(240).min(1);
+    .refine((value) => !hasControlCharacter(value), "Invalid text.");
+const label = text(ANALYSIS_LIMITS.labelChars).min(1);
 const id = z
     .string()
     .min(1)
@@ -17,7 +18,7 @@ const sourceId = text(256).min(1);
 const digest = z.string().regex(SHA256_HEX_PATTERN);
 const timestamp = z.string().datetime({ offset: true });
 const sourceIds = z.array(sourceId).max(128);
-const refs = z.array(id).min(1).max(100);
+const refs = z.array(id).min(1).max(ANALYSIS_LIMITS.evidenceRefs);
 const limitations = z.array(text(2000).min(1)).max(100);
 const observationSchema = z
     .object({
@@ -32,9 +33,9 @@ const designFindingSchema = z
     id,
     headline: label,
     screen: label,
-    notice: text(1500).min(1),
-    whyItMatters: text(1000).min(1),
-    suggestion: text(1000).min(1),
+    notice: text(ANALYSIS_LIMITS.noticeChars).min(1),
+    whyItMatters: text(ANALYSIS_LIMITS.whyItMattersChars).min(1),
+    suggestion: text(ANALYSIS_LIMITS.suggestionChars).min(1),
     severity: z.enum(["minor", "moderate", "major"]),
     confidence: z.enum(["low", "medium", "high"]),
     seenByStreamIds: sourceIds.min(1),
@@ -66,7 +67,7 @@ const analysisResultSchema = z
         id,
         title: label,
         headline: label.optional(),
-        experience: text(1200).min(1).optional(),
+        experience: text(ANALYSIS_LIMITS.experienceChars).min(1).optional(),
         summary: text(4000).min(1),
         impact: z.enum(["blocked_task", "friction", "recovery", "uncertain"]),
         affectedStreamIds: sourceIds.min(1),
@@ -79,8 +80,8 @@ const analysisResultSchema = z
         priorityReason: text(2000).min(1),
     })
         .strict())
-        .max(100),
-    designFindings: z.array(designFindingSchema).max(40).optional(),
+        .max(ANALYSIS_LIMITS.findings),
+    designFindings: z.array(designFindingSchema).max(ANALYSIS_LIMITS.designFindings).optional(),
     concernReviews: z
         .array(observationSchema
         .extend({
@@ -89,7 +90,7 @@ const analysisResultSchema = z
         reason: text(2000).min(1),
     })
         .strict())
-        .max(60)
+        .max(ANALYSIS_LIMITS.concernReviews)
         .optional(),
     limitations,
 })
@@ -100,8 +101,8 @@ export const analysisResponseSchema = analysisResultSchema
     .extend({
     findings: z
         .array(analysisResultSchema.shape.findings.element.required({ headline: true, experience: true }))
-        .max(100),
-    designFindings: z.array(designFindingSchema).max(40),
+        .max(ANALYSIS_LIMITS.findings),
+    designFindings: z.array(designFindingSchema).max(ANALYSIS_LIMITS.designFindings),
 })
     .required({ concernReviews: true });
 export const analysisResultJsonSchema = z.toJSONSchema(analysisResponseSchema);
@@ -469,15 +470,7 @@ export function validateAnalysisArtifact(value) {
         (artifact.status === "complete" && !coverage.complete))
         throw new Error("ANALYSIS_STATUS_INVALID");
     if (artifact.result !== null) {
-        // Concern accounting became required with revision 5, and headlines, experiences and design
-        // findings with revision 7. Keep each boundary stable when the prompt version advances; a later
-        // prompt must not regain legacy omissions.
-        const revision = Number(/^study-evidence-(\d+)$/.exec(artifact.promptVersion)?.[1] ?? 0);
-        const result = artifact.result;
-        if ((revision >= 5 && result.concernReviews === undefined) ||
-            (revision >= 7 &&
-                (result.designFindings === undefined ||
-                    result.findings.some((finding) => finding.headline === undefined || finding.experience === undefined))))
+        if (!hasRevisionFields(artifact.promptVersion, artifact.result))
             throw new Error("ANALYSIS_RESULT_SCHEMA_INVALID");
         validateAnalysisResult({ ...artifact, images: [] }, artifact.result);
     }

package/dist/cli/commands/analyze.js

@@ -6,7 +6,8 @@ import { listAnalyses } from "../../analysis/store.js";
 import { listAnalysisExecutions } from "../../analysis/store-executions.js";
 import { resolveRunPath } from "../../run/locate.js";
 import { CWD_OPTION_DESCRIPTION, discoverCliKeys, JSON_OPTION_DESCRIPTION, RUN_OPTION_DESCRIPTION, writeResult, humanError, wantsJson, } from "../io.js";
-import { analysisFindings, formatFindings, missingRunFindings, readRunAnalysis, } from "../findings.js";
+import { analysisFindings, missingRunFindings, readRunAnalysis, } from "../findings.js";
+import { formatFindings } from "../findings-text.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) {

package/dist/cli/commands/notes.js

@@ -1,8 +1,11 @@
 import { renderObserver } from "../../observer/render.js";
 import { loadRunBundlePrepared, resolveRunPath } from "../../run/locate.js";
-import { addRunNote, formatRunTime, readRunNotes, runParticipantCaptions, } from "../../run/notes.js";
-import { streamParticipantIdOf } from "../../run/participant-records.js";
+import { readRunNotes } from "../../run/note-files.js";
+import { byRunTime } from "../../run/note-shape.js";
+import { addRunNote } from "../../run/notes.js";
+import { runParticipantCaptions, streamParticipantIdOf } from "../../run/participant-records.js";
 import { resolvePhysicalCwd, runIdOf } from "../../run/paths.js";
+import { formatRunTime } from "../../run/run-clock.js";
 import { runNotFoundMessage } from "../../run/run-not-found.js";
 import { cli } from "../invocation.js";
 import { CWD_OPTION_DESCRIPTION, humanError, JSON_OPTION_DESCRIPTION, writeResult, } from "../io.js";
@@ -42,7 +45,6 @@ function parseRunTime(value) {
     const match = /^(\d{1,4}):([0-5]\d)$/.exec(value.trim());
     return match ? (Number(match[1]) * 60 + Number(match[2])) * 1000 : null;
 }
-const byRunTime = (notes) => [...notes].sort((left, right) => left.atMs - right.atMs || left.createdAt.localeCompare(right.createdAt));
 async function handleNotes(io, run, text, options, command) {
     const base = {
         schema: NOTES_RESULT_SCHEMA,

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

@@ -134,7 +134,11 @@ async function stopActiveRuns(io, signal, stopping, options) {
     // not swept; verify grades a file that names a receipt's id local_only.
     Promise.all(stopping
         .filter((stop) => stop.report !== null)
-        .map((stop) => scrubRunSandboxIds(stop.run.paths).catch(() => undefined))));
+        .map((stop) => scrubRunSandboxIds(stop.run.paths).catch((error) => {
+        // A file the sweep refused to read may still name a sandbox; say which.
+        if (error instanceof Error)
+            say(io, `humanish: ${signal}: ${error.message}`);
+    }))));
     const finished = await withDeadline(work, deadlineMs, options.deadline);
     for (const stop of stopping) {
         if (stop.report === null)

package/dist/cli/commands/runs.js

@@ -11,7 +11,8 @@ import { addRunOptions, handleRun } from "./run-command.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";
+import { readRunFindings } from "../findings.js";
+import { formatFindings } from "../findings-text.js";
 import { cli } from "../invocation.js";
 export function registerRunCommand(parent, io) {
     addRunOptions(parent

package/dist/cli/commands/setup.js

@@ -1,5 +1,5 @@
 import { Command } from "commander";
-import { listUserKeys, resolveKeyName, setUserKey, unsetUserKey, userKeyStorePath, } from "../../keys/key-resolution.js";
+import { KEY_VENDORS, 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";
@@ -270,7 +270,7 @@ export function registerKeysCommand(parent, io) {
         .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. Without one, a terminal asks for each missing key in turn.")
+        .argument("[vendor-or-name]", `A vendor alias (${KEY_VENDORS.join(", ")}) 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)
@@ -288,7 +288,7 @@ export function registerKeysCommand(parent, io) {
                 action: "set",
                 store: storePath,
                 names: [],
-                message: `Not a vendor alias or valid env name: ${vendorOrName}. Vendors: openai, e2b, anthropic, github, agentmail.`,
+                message: `Not a vendor alias or valid env name: ${vendorOrName}. Vendors: ${KEY_VENDORS.join(", ")}.`,
             };
             writeResult(command, io, result, formatKeysHuman);
             io.setExitCode(2);

package/dist/cli/commands/study-format.d.ts

@@ -3,7 +3,10 @@ import type { CuaActorStudyResult } from "../../routes/computer-use/types.js";
 import type { ScriptedBrowserStudyResult } from "../../routes/scripted/types.js";
 import type { TerminalProductStudyResult } from "../../routes/terminal/types.js";
 import type { ConcurrentSharedWorldStudyResult } from "../../routes/shared-world/types.js";
+import type { StudySubject } from "../../study/types.js";
 export declare function formatConcurrentSharedWorldStudyHuman(result: ConcurrentSharedWorldStudyResult): HumanOutput;
 export declare function formatTerminalStudyHuman(result: TerminalProductStudyResult): HumanOutput;
-export declare function formatScriptedStudyHuman(result: ScriptedBrowserStudyResult): HumanOutput;
-export declare function formatCuaStudyHuman(result: CuaActorStudyResult): HumanOutput;
+/** `subject` is the study's declared subject, which names it when the result has no URL. */
+export declare function formatScriptedStudyHuman(result: ScriptedBrowserStudyResult, subject: StudySubject): HumanOutput;
+/** `subject` is the study's declared subject, which names it when the result has no URL. */
+export declare function formatCuaStudyHuman(result: CuaActorStudyResult, subject: StudySubject): HumanOutput;

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

@@ -1,12 +1,18 @@
 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. */
+/**
+ * A run's first lines: the command that ran, whether it was a dry run, how it ended, and its route.
+ * `runOk` is the run's own ok, which automaticAnalysisEnvelope keeps when an analysis that did not
+ * complete turns `ok` false. That run finished, and the line says so.
+ */
 function runHeader(result, route) {
     const kind = result.dryRun === true ? "dry run" : result.dryRun === false ? "live run" : "run";
-    return [
-        `humanish run ${result.studyId}: ${kind} ${result.ok ? "finished" : "failed"}`,
-        `route: ${route}`,
-    ];
+    const ending = result.ok
+        ? "finished"
+        : result.runOk === true
+            ? "finished; the analysis did not complete"
+            : "failed";
+    return [`humanish run ${result.studyId}: ${kind} ${ending}`, `route: ${route}`];
 }
 /**
  * A run's human output: its lines on stdout and, when it failed with an error, that error on
@@ -31,6 +37,18 @@ function sandboxIdsLine(result) {
         ? [`sandbox ids: .humanish/runs/${result.runId}/sandbox-receipts.ndjson`]
         : [];
 }
+/**
+ * How a run's output names its subject: by the URL its participants open. A product studied at a
+ * desktop has no URL, so it is named with its source, as in `humanish (desktop-cli)`. A refusal
+ * made before the route resolved a URL has none either, so it names the URL the study declares.
+ */
+function subjectName(appUrl, subject) {
+    if (appUrl !== "")
+        return appUrl;
+    if (subject.product !== undefined)
+        return `${subject.product.name} (${subject.source})`;
+    return subject.appUrl ?? subject.serve?.url ?? subject.source;
+}
 /** A participant's status in words: a dry run's placeholder status says that nothing ran live. */
 function participantStatus(status) {
     return status === "contract_proof_only" ? "dry run, nothing ran live" : status;
@@ -83,12 +101,13 @@ export function formatTerminalStudyHuman(result) {
         ...result.warnings.map((warning) => `warning: ${warning}`),
     ]);
 }
-export function formatScriptedStudyHuman(result) {
+/** `subject` is the study's declared subject, which names it when the result has no URL. */
+export function formatScriptedStudyHuman(result, subject) {
     return withError(result.error, [
         ...runHeader(result, "scripted"),
         `run: ${result.runId}`,
         `actor: ${result.actor}`,
-        `subject: ${result.appUrl}`,
+        `subject: ${subjectName(result.appUrl, subject)}`,
         ...(result.scenario
             ? [
                 `scenario: ${result.scenario.id} @ ${result.scenario.sourceDigest.slice(0, 12)} (${result.scenario.source}, ${result.scenario.steps} step${result.scenario.steps === 1 ? "" : "s"})`,
@@ -108,12 +127,13 @@ export function formatScriptedStudyHuman(result) {
         ...result.warnings.map((warning) => `warning: ${warning}`),
     ]);
 }
-export function formatCuaStudyHuman(result) {
+/** `subject` is the study's declared subject, which names it when the result has no URL. */
+export function formatCuaStudyHuman(result, subject) {
     return withError(result.error, [
         ...runHeader(result, "computer-use"),
         `run: ${result.runId}`,
         `actor: ${result.actor}`,
-        `subject: ${result.appUrl}`,
+        `subject: ${subjectName(result.appUrl, subject)}`,
         ...(result.subject?.source === "clone"
             ? [
                 `repo: ${result.subject.repo}${result.subject.commit ? `@${result.subject.commit.slice(0, 12)}` : ""}${result.subject.envNames && result.subject.envNames.length > 0 ? ` env=[${result.subject.envNames.join(", ")}]` : ""}`,

package/dist/cli/commands/study-route-computer-use.js

@@ -57,7 +57,7 @@ function refuseCua(args, dryRun, code, message) {
         dryRun,
         runId: args.options.runId ?? "not-created",
     });
-    writeResult(args.command, args.io, result, formatCuaStudyHuman);
+    writeResult(args.command, args.io, result, (value) => formatCuaStudyHuman(value, args.config.subject));
     args.io.setExitCode(2);
 }
 /** Parses the options, or writes the refusal and returns undefined. */
@@ -236,7 +236,7 @@ async function reportCuaRun(args, prepared, result, live) {
             ],
         };
     }
-    writeResult(args.command, args.io, output, formatCuaStudyHuman);
+    writeResult(args.command, args.io, output, (value) => formatCuaStudyHuman(value, args.config.subject));
     args.io.setExitCode(result.ok && automaticAnalysisSucceeded(result) ? 0 : 2);
     await writeRunFindings(args.command, args.io, args.options.cwd, result);
     if (server && (result.observer?.ok || attachedObserver)) {

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

@@ -34,7 +34,7 @@ export function scriptedRouteRun(args) {
                 throw new Error(`Expected the scripted route, got ${outcome.route}.`);
             }
             const result = outcome.result;
-            writeResult(args.command, args.io, result, formatScriptedStudyHuman);
+            writeResult(args.command, args.io, result, (value) => formatScriptedStudyHuman(value, args.config.subject));
             args.io.setExitCode(result.ok && automaticAnalysisSucceeded(result) ? 0 : 2);
             await writeRunFindings(args.command, args.io, args.options.cwd, result);
             // Watch mode serves the Observer the route rendered through its finished run.

package/dist/cli/commands/tui.js

@@ -1,7 +1,8 @@
 import { existsSync } from "node:fs";
 import { resolve } from "node:path";
 import { Command } from "commander";
-import { setUserKey } from "../../keys/key-resolution.js";
+import { LISTED_KEYS, setUserKey } from "../../keys/key-resolution.js";
+import { keyStatus, keyStatusLine } from "../../keys/key-status.js";
 import { saveCommsConnection } from "../../comms/connections.js";
 import { readCommsSetup } from "../../comms/setup.js";
 import { checkCommsConnection, configureCommsStudy, } from "../../comms/setup.js";
@@ -160,13 +161,11 @@ async function runTuiSession(loaded, runtime, cwd, discoveredKeys) {
         runIndexCache: new RunIndexCache(),
         observerSession: createTuiObserverSession(cwd),
     };
-    let connectionNotice;
+    let returnTo;
     try {
         for (;;) {
             const outcome = await loaded.startTui({
-                ...(connectionNotice === undefined
-                    ? {}
-                    : { initialScreen: "connections", connectionNotice }),
+                ...returnTo,
                 cwd,
                 version: { cli: CLI_VERSION },
                 capabilities: tuiCapabilities(session),
@@ -175,9 +174,17 @@ async function runTuiSession(loaded, runtime, cwd, discoveredKeys) {
             });
             if (typeof outcome === "number")
                 return outcome;
-            if (outcome.action !== "agentmail-key")
+            returnTo =
+                outcome.action === "agentmail-key"
+                    ? { initialScreen: "connections", connectionNotice: await storeAgentmailKey(session) }
+                    : outcome.action === "provider-key"
+                        ? {
+                            initialScreen: "keys",
+                            connectionNotice: await storeProviderKey(session, outcome.name),
+                        }
+                        : undefined;
+            if (returnTo === undefined)
                 return 1;
-            connectionNotice = await storeAgentmailKey(session);
         }
     }
     finally {
@@ -197,6 +204,14 @@ function connectionEnv(session) {
 function tuiCapabilities(session) {
     const { cwd, runtime, sessionEnv, runIndexCache, observerSession } = session;
     return {
+        keys: {
+            // The project's overlay and the stores, as `humanish keys` reads them from this directory.
+            status: async () => (await keyStatus({ cwd, env: connectionEnv(session) })).map((row) => ({
+                name: row.name,
+                set: row.source !== null,
+                line: keyStatusLine(row),
+            })),
+        },
         comms: {
             read: async () => ({
                 ...(await readCommsSetup(cwd, connectionEnv(session))),
@@ -270,21 +285,48 @@ function tuiCapabilities(session) {
         },
     };
 }
+const ENTRY_CANCELLED = "Key entry cancelled. Nothing was changed.";
+const ENTRY_FAILED = "Could not store the key. Use a single non-empty line and check key-store permissions.";
+/**
+ * Asks for one key with hidden input, after the surface has unmounted, and stores it in the user
+ * store. Only the host reads the credential. A value that discovery filled into this session is
+ * dropped so the stored one is read; an explicit env or file value still wins.
+ */
+async function promptAndStoreKey(session, name, label) {
+    const { runtime, sessionEnv } = session;
+    const value = await runtime.promptSecret(label, runtime.stdin, runtime.stdout);
+    if (value === null || value === "")
+        return "cancelled";
+    setUserKey(name, value, sessionEnv);
+    if (session.discoveredKeys.has(name))
+        delete sessionEnv[name];
+    return "stored";
+}
+/**
+ * A key from the keys screen, asked for and stored as `humanish keys set <vendor>` does. Resolves to
+ * the notice the remounted keys screen shows.
+ */
+async function storeProviderKey(session, name) {
+    if (!LISTED_KEYS.some((key) => key.name === name))
+        return `${name} is not a key humanish keys lists. Nothing was changed.`;
+    try {
+        return (await promptAndStoreKey(session, name, `Value for ${name}`)) === "stored"
+            ? `${name} stored.`
+            : ENTRY_CANCELLED;
+    }
+    catch {
+        return ENTRY_FAILED;
+    }
+}
 /**
  * Prompts for the AgentMail key after the surface has unmounted, stores it and checks it. Resolves
  * to the notice the remounted connections screen shows.
  */
 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 || value === "")
-        return "Key entry cancelled. Nothing was changed.";
+    const { cwd, runtime } = session;
     try {
-        setUserKey("AGENTMAIL_API_KEY", value, sessionEnv);
-        // Refresh only a value filled implicitly by discovery; explicit env/file wins.
-        if (session.discoveredKeys.has("AGENTMAIL_API_KEY"))
-            delete sessionEnv.AGENTMAIL_API_KEY;
+        if ((await promptAndStoreKey(session, "AGENTMAIL_API_KEY", "AgentMail API key")) !== "stored")
+            return ENTRY_CANCELLED;
         const saved = await saveCommsConnection(cwd);
         const storedNotice = saved.ok
             ? "Key stored. Project connection saved."
@@ -301,6 +343,6 @@ async function storeAgentmailKey(session) {
             : `${storedNotice} ${check.message}`;
     }
     catch {
-        return "Could not store the key. Use a single non-empty line and check key-store permissions.";
+        return ENTRY_FAILED;
     }
 }

package/dist/cli/doctor.js

@@ -2,8 +2,9 @@ import { readFile, readdir } from "node:fs/promises";
 import { homedir } from "node:os";
 import { existsSync } from "node:fs";
 import path from "node:path";
-import { probeKeySources, } from "../keys/key-resolution.js";
+import { DOCTOR_KEYS, probeKeySources, } from "../keys/key-resolution.js";
 import { desktopPeerAdvice, humanishInstall, } from "../substrates/e2b/peer-install.js";
+import { describeSandboxCeiling, sandboxCeiling } from "../substrates/e2b/lifetime.js";
 import { nodeSupportsTui, terminalSurfaceMessage, TUI_BUNDLE_URL } from "../tui/contract.js";
 import { detectLocalAgents, localAgentDoctorMessage, localAgentReady, NO_LOCAL_AGENT_MESSAGE, } from "../actors/local-agent/cli.js";
 import { leftoverClaudeTranscripts } from "../actors/local-agent/claude-participant.js";
@@ -95,6 +96,7 @@ export async function doctor(cwdInput, options = {}) {
     const checks = [
         ...(await projectChecks(projectRoot)),
         await desktopSdkCheck(setup),
+        sandboxCeilingCheck(env),
         terminalSurfaceCheck(),
         ...versionCheck(env),
         ...localAgentChecks(agents),
@@ -191,6 +193,11 @@ async function runtimeIgnoreCheck(projectRoot) {
             : `.gitignore does not list .humanish/; run ${cli("init --yes")}`,
     };
 }
+/** The longest sandbox lifetime the E2B planners allow, and where that number came from. */
+function sandboxCeilingCheck(env) {
+    const ceiling = sandboxCeiling(env);
+    return { name: "e2b sandbox ceiling", ok: ceiling.ok, message: describeSandboxCeiling(ceiling) };
+}
 /**
  * The optional peer dep every live browser and terminal route needs. `npx -y humanish` does not
  * pull optional peers, so without this check an adopter's first live run fails on it, safely and at
@@ -266,7 +273,7 @@ function versionCheck(env) {
 }
 /** 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"]);
+    const keyNames = new Set(DOCTOR_KEYS);
     let receivingKey = null;
     if (study) {
         const { resolveStudyManifest } = await import("../study/discover.js");

package/dist/cli/findings-text.d.ts

@@ -0,0 +1,5 @@
+import type { AnalysisFindings } from "./findings.js";
+/** The full findings block: the analysis, every finding with its evidence, and its limitations. */
+export declare function formatFindings(view: AnalysisFindings): string[];
+/** At most `limit` findings, one line each, and the command that prints all of them. */
+export declare function formatFindingsSummary(view: AnalysisFindings, fullCommand: string, limit?: number): string[];