humanish 0.109.1 → 0.110.1

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

@@ -6,6 +6,7 @@ import { redactText } from "../../evidence/redaction.js";
 import { cliAnalysisOptions } from "./analysis-signals.js";
 import { parseObserverPort, wantsJson, writeResult, } from "../io.js";
 import { followObserver, showObserver, staticObserverOpen, withObserverServer, } from "../observer-follow.js";
+import { writeRunFindings } from "../findings.js";
 import { formatConcurrentSharedWorldStudyHuman } from "./study-format.js";
 import { resolveRouteShouldOpen, watchFinishedPlan } from "./study-route-open.js";
 import { rosterOf } from "../../study/parse/actors.js";
@@ -118,6 +119,7 @@ export function sharedWorldRouteRun(args) {
             }
             writeResult(args.command, args.io, output, formatConcurrentSharedWorldStudyHuman);
             args.io.setExitCode(result.ok && automaticAnalysisSucceeded(result) ? 0 : 2);
+            await writeRunFindings(args.command, args.io, args.options.cwd, result);
             if (server && output.observer?.ok) {
                 await followObserver(args.io, output.observer, server);
             }

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

@@ -2,6 +2,7 @@ import { automaticAnalysisSucceeded } from "../../analysis/automatic-completion.
 import { Command } from "commander";
 import { cliAnalysisOptions } from "./analysis-signals.js";
 import { wantsJson, writeResult } from "../io.js";
+import { writeRunFindings } from "../findings.js";
 import { showObserver } from "../observer-follow.js";
 import { formatTerminalStudyHuman } from "./study-format.js";
 import { observerOpen, resolveRouteShouldOpen, watchFinishedPlan } from "./study-route-open.js";
@@ -35,6 +36,7 @@ export function terminalRouteRun(args) {
             const result = outcome.result;
             writeResult(args.command, args.io, result, formatTerminalStudyHuman);
             args.io.setExitCode(result.ok && automaticAnalysisSucceeded(result) ? 0 : 2);
+            await writeRunFindings(args.command, args.io, args.options.cwd, result);
             if (finishedPlan !== undefined && result.ok && result.observer !== undefined) {
                 await showObserver({
                     command: args.command,

package/dist/cli/commands/study.js

@@ -3,7 +3,7 @@ import { resolve } from "node:path";
 import { Command, Option } from "commander";
 import { inspectStudyManifest, listStudyManifests } from "../../study/discover.js";
 import { runStudyPreflight, } from "../../study/preflight.js";
-import { applyEnvFileOption, CWD_OPTION_DESCRIPTION, ENV_FILE_OPTION_DESCRIPTION, JSON_OPTION_DESCRIPTION, parsePositiveInteger, writeResult, humanError, } from "../io.js";
+import { applyEnvFileOption, CWD_OPTION_DESCRIPTION, DOTENV_OPTION_DESCRIPTION, dotenvPathOf, envFileAliasOption, JSON_OPTION_DESCRIPTION, parsePositiveInteger, writeResult, humanError, } from "../io.js";
 export function registerStudyCommands(parent, io) {
     const study = parent
         .command("study")
@@ -36,7 +36,8 @@ function checkCommand(command, io) {
         .choices(["metadata", "public-preview", "sandbox-loopback", "prepared-host"])
         .default("metadata"))
         .option("--timeout-ms <ms>", "Target reachability timeout.", String(30_000))
-        .option("--env-file <path>", ENV_FILE_OPTION_DESCRIPTION)
+        .option("--dotenv <path>", DOTENV_OPTION_DESCRIPTION)
+        .addOption(envFileAliasOption())
         .option("--json", JSON_OPTION_DESCRIPTION)
         .action((name, options, command) => handleStudyCheck(io, name, options, command));
 }
@@ -54,7 +55,7 @@ async function handleStudyCheck(io, name, options, command) {
     if (!(await applyEnvFileOption({
         command,
         cwd: options.cwd,
-        envFile: options.envFile,
+        envFile: dotenvPathOf(options, command, io),
         io,
     }))) {
         return;

package/dist/cli/commands/tui.js

@@ -19,7 +19,7 @@ import { readRunDetail } from "../../run/detail.js";
 import { launchRun, readLaunchLogTail } from "../../tui/launch.js";
 import { TUI_MIN_NODE_MAJOR, nodeSupportsTui, TUI_BUNDLE_URL, } from "../../tui/contract.js";
 import { detectAgentSession } from "../../actors/agent-session.js";
-import { applyEnvFileOption, CLI_VERSION, CWD_OPTION_DESCRIPTION, ENV_FILE_OPTION_DESCRIPTION, JSON_OPTION_DESCRIPTION, markInvocationEnvelopeWritten, wantsJson, } from "../io.js";
+import { applyEnvFileOption, CLI_VERSION, CWD_OPTION_DESCRIPTION, DOTENV_OPTION_DESCRIPTION, dotenvPathOf, envFileAliasOption, JSON_OPTION_DESCRIPTION, markInvocationEnvelopeWritten, wantsJson, } from "../io.js";
 export const defaultTuiRuntime = {
     checkComms: checkCommsConnection,
     promptSecret,
@@ -59,7 +59,8 @@ export function registerTuiCommand(parent, io, runtime = defaultTuiRuntime) {
         .description("Browse studies and runs in an interactive terminal UI. It refuses detected agent sessions and non-TTY input or output; agents use humanish study list --json, humanish study show <study> --json and humanish runs --json.")
         .summary("Browse studies and runs in a terminal UI for people.")
         .option("--cwd <path>", CWD_OPTION_DESCRIPTION, ".")
-        .option("--env-file <path>", ENV_FILE_OPTION_DESCRIPTION)
+        .option("--dotenv <path>", DOTENV_OPTION_DESCRIPTION)
+        .addOption(envFileAliasOption())
         .option("--force", "Open it anyway in a session that looks like an agent's.")
         .option("--json", JSON_OPTION_DESCRIPTION)
         .action((options, command) => handleTui(io, runtime, options, command));
@@ -89,7 +90,7 @@ async function handleTui(io, runtime, options, command) {
     if (!(await applyEnvFileOption({
         command,
         cwd: options.cwd,
-        envFile: options.envFile,
+        envFile: dotenvPathOf(options, command, io),
         io,
         env: runtime.env,
         onDiscovered: (names) => names.forEach((name) => discoveredKeys.add(name)),

package/dist/cli/commands/watch.js

@@ -4,7 +4,7 @@ import { WATCH_SAFE_NOT_APPLICABLE_MESSAGE } from "../../observer/exposure.js";
 import { runDryRun } from "../../run/dry-run.js";
 import { runStudyCommand } from "./study-run.js";
 import { addRunOptions, studyOnlyFlags } from "./run-command.js";
-import { applyEnvFileOption, collectRepeated, formatRunHuman, parseObserverPort, parsePositiveInteger, wantsJson, writeResult, } from "../io.js";
+import { applyEnvFileOption, collectRepeated, dotenvPathOf, formatRunHuman, parseObserverPort, parsePositiveInteger, wantsJson, writeResult, } from "../io.js";
 import { followObserver, formatObserverHuman, watchExposeRequested } from "../observer-follow.js";
 export function registerWatchCommand(parent, io) {
     // A run's flags come from addRunOptions, the helper `run` uses, so the two cannot drift.
@@ -59,7 +59,7 @@ async function handleWatch(io, named, parsed, command) {
     if (!(await applyEnvFileOption({
         command,
         cwd: options.cwd,
-        envFile: options.envFile,
+        envFile: dotenvPathOf(options, command, io),
         io,
         // runStudyCommand discovers keys for a live study; a preview run needs none.
         discoverKeys: false,

package/dist/cli/doctor.d.ts

@@ -1,4 +1,5 @@
-import { type KeyResolutionDeps } from "../keys/key-resolution.js";
+import { type KeyResolutionDeps, type DotenvLoad } from "../keys/key-resolution.js";
+import { type HumanishInstall } from "../substrates/e2b/peer-install.js";
 import { type DetectLocalAgentsOptions } from "../actors/local-agent/cli.js";
 import { type StudySetupCheckArgs } from "../study/doctor.js";
 declare const DOCTOR_SCHEMA = "humanish.doctor-result.v1";
@@ -35,7 +36,9 @@ export interface DoctorResult {
  */
 export declare const DESKTOP_SDK_FLOOR = "2.3.2";
 /** The advisory `doctor` attaches to an installed desktop SDK older than the floor, else undefined. */
-export declare function desktopSdkAdvisory(version: string | undefined): string | undefined;
+export declare function desktopSdkAdvisory(version: string | undefined, install?: () => HumanishInstall): string | undefined;
+/** The doctor line for an absent desktop SDK, with the install command for where humanish runs from. */
+export declare function missingDesktopSdkMessage(install: HumanishInstall): string;
 /** A row as a check writes it. Doctor derives `status`; an advisory row sets "note" itself. */
 export type DoctorCheckDraft = Omit<DoctorResult["checks"][number], "status"> & {
     status?: "note";
@@ -48,5 +51,7 @@ export declare function doctor(cwdInput: string, options?: {
     keyDeps?: KeyResolutionDeps;
     /** The hosted Codex participant's operator handshake; tests replace it. */
     codexParticipantReadiness?: StudySetupCheckArgs["codexParticipantReadiness"];
+    /** What `--dotenv` loaded, so a key row names the file that supplied it. */
+    dotenv?: DotenvLoad;
 }): Promise<DoctorResult>;
 export {};

package/dist/cli/doctor.js

@@ -1,9 +1,12 @@
-import { readFile } from "node:fs/promises";
+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 { desktopPeerAdvice, humanishInstall, } from "../substrates/e2b/peer-install.js";
 import { nodeSupportsTui, terminalSurfaceMessage, TUI_BUNDLE_URL } from "../tui/contract.js";
 import { detectLocalAgents, localAgentDoctorMessage, NO_LOCAL_AGENT_MESSAGE, } from "../actors/local-agent/cli.js";
+import { leftoverClaudeTranscripts } from "../actors/local-agent/claude-participant.js";
 import { studySetupChecks, studiesByRequiredKey, } from "../study/doctor.js";
 import { prepareSelectedOutputDirectory, } from "../run/contained-output.js";
 import { implicitProjectDirectoryExists, readImplicitProjectFile, validateCwd, } from "../run/project.js";
@@ -16,7 +19,7 @@ const DOCTOR_SCHEMA = "humanish.doctor-result.v1";
  */
 export const DESKTOP_SDK_FLOOR = "2.3.2";
 /** The advisory `doctor` attaches to an installed desktop SDK older than the floor, else undefined. */
-export function desktopSdkAdvisory(version) {
+export function desktopSdkAdvisory(version, install = humanishInstall) {
     if (version === undefined)
         return undefined;
     const parse = (value) => value
@@ -31,9 +34,14 @@ export function desktopSdkAdvisory(version) {
         (have[0] === floor[0] &&
             (have[1] < floor[1] || (have[1] === floor[1] && have[2] < floor[2])));
     return older
-        ? `@e2b/desktop ${version} is older than ${DESKTOP_SDK_FLOOR}, the supported floor for background command cleanup and stdin handles (older releases could keep the CLI alive for minutes after its result). Update with \`npm i -D @e2b/desktop@latest\`.`
+        ? `@e2b/desktop ${version} is older than ${DESKTOP_SDK_FLOOR}, the supported floor for background command cleanup and stdin handles (older releases could keep the CLI alive for minutes after its result). To update it: ${desktopPeerAdvice(install(), "@e2b/desktop@latest").advice}`
         : undefined;
 }
+/** The doctor line for an absent desktop SDK, with the install command for where humanish runs from. */
+export function missingDesktopSdkMessage(install) {
+    const { where, advice } = desktopPeerAdvice(install);
+    return `optional peer @e2b/desktop is not installed${where}: dry runs work, but a live run with a desktop participant fails when it starts. ${advice}`;
+}
 /** The version of the @e2b/desktop that `import("@e2b/desktop")` resolves to from here, if readable. */
 async function installedDesktopSdkVersion() {
     try {
@@ -65,7 +73,7 @@ export async function doctor(cwdInput, options = {}) {
     }
     const env = options.env ?? process.env;
     const agents = await detectLocalAgents({ ...options.localAgents, env });
-    const { probes, receivingKey } = await probeDoctorKeys(cwd, env, options.study, options.keyDeps);
+    const { probes, receivingKey } = await probeDoctorKeys(cwd, env, options.study, options.keyDeps, options.dotenv);
     const keyPresent = (name) => probes.some((probe) => probe.name === name && probe.source !== null);
     const setup = options.study
         ? await studySetupChecks({
@@ -86,6 +94,7 @@ export async function doctor(cwdInput, options = {}) {
         await desktopSdkCheck(setup),
         terminalSurfaceCheck(),
         ...localAgentChecks(agents),
+        await claudeTranscriptCheck(env),
         ...keyChecks(probes, receivingKey, setup, keyUsers),
         ...(setup?.checks ?? [
             {
@@ -205,7 +214,7 @@ async function desktopSdkCheck(setup) {
             ? `optional peer @e2b/desktop ${version ?? "(version unread)"} is installed; provider access is not tested${advisory === undefined ? "" : `. ${advisory}`}`
             : setup?.desktop === false
                 ? "optional peer @e2b/desktop is absent; not required by the selected route"
-                : "optional peer @e2b/desktop is not installed: dry runs work, but a live run with a desktop participant fails when it starts. Install it with `npm i -D @e2b/desktop`.",
+                : missingDesktopSdkMessage(humanishInstall()),
     };
 }
 /**
@@ -237,7 +246,7 @@ function terminalSurfaceCheck() {
     };
 }
 /** Probes the live-run keys, plus the receiving-email key a real-comms study names. */
-async function probeDoctorKeys(cwd, env, study, keyDeps) {
+async function probeDoctorKeys(cwd, env, study, keyDeps, dotenv) {
     const keyNames = new Set(["OPENAI_API_KEY", "E2B_API_KEY", "GH_TOKEN", "CODEX_API_KEY"]);
     let receivingKey = null;
     if (study) {
@@ -254,6 +263,7 @@ async function probeDoctorKeys(cwd, env, study, keyDeps) {
         cwd,
         env,
         ...(keyDeps === undefined ? {} : { deps: keyDeps }),
+        ...(dotenv === undefined ? {} : { dotenv }),
     });
     return { probes, receivingKey };
 }
@@ -273,6 +283,35 @@ function localAgentChecks(agents) {
         message: localAgentDoctorMessage(agent),
     }));
 }
+/**
+ * Earlier releases let Claude Code save a transcript for every participant, with each screenshot it
+ * read, under its projects folder and outside `.humanish/`. Participants now run with
+ * `--no-session-persistence`; this row counts what earlier runs left and prints the command that
+ * removes it. doctor never deletes anything.
+ */
+async function claudeTranscriptCheck(env) {
+    const found = await leftoverClaudeTranscripts(env, env.HOME ?? homedir(), (directory) => readdir(directory));
+    const name = "claude participant transcripts";
+    if ("unreadable" in found)
+        return {
+            name,
+            ok: true,
+            status: "note",
+            message: `could not list ${found.directory} (${found.unreadable}), so transcripts from earlier Claude Code participants were not counted. Check the folder for names ending in -humanish-claude-session-XXXXXX.`,
+        };
+    const count = found.names.length;
+    const folders = `${count} transcript folder${count === 1 ? "" : "s"} from earlier Claude Code participants under ${found.directory} hold every screenshot those runs read, unblurred.`;
+    return {
+        name,
+        ok: true,
+        ...(count === 0 ? {} : { status: "note" }),
+        message: count === 0
+            ? `no transcript from an earlier Claude Code participant under ${found.directory}`
+            : found.removeCommand === undefined
+                ? `${folders} Remove these folders there: ${found.names.join(", ")}`
+                : `${folders} Remove them with: ${found.removeCommand}`,
+    };
+}
 /** "try-live", "try-live and local-browser", "a, b and c". */
 function studyList(studies) {
     return studies.length < 2
@@ -281,7 +320,7 @@ function studyList(studies) {
 }
 /**
  * Provider-key discovery: which source supplies each live-run key, through the same
- * chain a live command resolves (env/--env-file, project overlay, vendor stores, the
+ * chain a live command resolves (env/--dotenv, project overlay, vendor stores, the
  * humanish user store). Values never appear; sources and fill commands do.
  *
  * With --study, a key the selected route requires fails when missing. Without it, `keyUsers` maps
@@ -292,7 +331,7 @@ function keyChecks(probes, receivingKey, setup, keyUsers) {
     return probes.map((probe) => {
         const present = probe.source !== null;
         const hint = probe.name === receivingKey
-            ? `provide ${probe.name} through process env or --env-file`
+            ? `provide ${probe.name} through process env or --dotenv`
             : probe.hint;
         if (!setup) {
             const users = keyUsers?.get(probe.name) ?? [];

package/dist/cli/findings.d.ts

@@ -0,0 +1,103 @@
+import type { Command } from "commander";
+import type { AutomaticAnalysisOutcome } from "../analysis/job.js";
+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];
+/** `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 {
+    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. */
+    elapsedMs: number | null;
+    at: string | null;
+    /** The capture file relative to the project directory, or null for nonvisual evidence. */
+    capture: string | null;
+}
+interface FindingView {
+    id: string;
+    title: string;
+    summary: string;
+    impact: Finding["impact"];
+    confidence: Finding["confidence"];
+    recovery: Finding["recovery"];
+    affected: {
+        streamId: string;
+        label: string;
+    }[];
+    exposedCount: number;
+    evidence: FindingEvidence[];
+    nextStep: string;
+    /** The latest human review note on this finding version (`analyze correct`), or null. */
+    correction: {
+        status: "confirmed" | "dismissed" | "amended";
+        reason: string;
+        replacementClaim: string | null;
+    } | null;
+}
+export interface AnalysisFindings {
+    schema: typeof ANALYSIS_FINDINGS_SCHEMA;
+    runId: string;
+    state: FindingsState;
+    /** The stable code behind a state other than ready, when one is recorded. */
+    reason: string | null;
+    message: string;
+    /** The command that gets findings for this run, or null when none can. */
+    next: string | null;
+    analysisId: string | null;
+    status: AnalysisArtifact["status"] | null;
+    provider: AnalysisArtifact["provider"] | null;
+    model: string | null;
+    completedAt: string | null;
+    estimatedCostUsd: number | null;
+    /** The run directory relative to the project directory; null when the run was not found. */
+    runPath: string | null;
+    /** analysis.json relative to the project directory. */
+    path: string | null;
+    summary: string | null;
+    /** Highest priority first, as the analysis ranked them. */
+    findings: FindingView[];
+    limitations: string[];
+    warnings: string[];
+}
+interface FindingsSource {
+    runId: string;
+    /** The bundle's mode; undefined when run.json could not be read. */
+    mode: string | undefined;
+    /** The run directory relative to the project directory. */
+    runRoot: string;
+    loaded: LoadedAnalysis;
+    /** ` --cwd <dir>` when the commands this view names need it, or "". */
+    cwdFlag: string;
+}
+/** The findings view of a run's selected analysis, or why it has none. */
+export declare function analysisFindings(source: FindingsSource): AnalysisFindings;
+/**
+ * The run's bundle mode and its selected analysis: `analysisId`, or the version `analyze show`
+ * defaults to. Null when the run is missing or its storage is unsafe.
+ */
+export declare function readRunAnalysis(cwd: string, run: string, analysisId?: string): Promise<FindingsSource | null>;
+/** The view of a run that could not be found. */
+export declare function missingRunFindings(cwd: string, run: string): AnalysisFindings;
+/** The findings of a run's selected analysis, or why it has none. */
+export declare function readRunFindings(cwd: string, run: string, analysisId?: string): Promise<AnalysisFindings>;
+/** 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[];
+/**
+ * The end of a live run's human output, after its `analysis:` line: the findings of the analysis
+ * the run just completed. Prints nothing for --json, or when the run's analysis did not complete,
+ * since that line already says why.
+ */
+export declare function writeRunFindings(command: Command, io: CliIo, cwd: string, result: {
+    runId?: string;
+    automaticAnalysis?: AutomaticAnalysisOutcome;
+}): Promise<void>;
+export {};