humanish 0.110.0 → 0.110.1

package/dist/cli/commands/runs.js

@@ -1,14 +1,16 @@
 import path from "node:path";
 import { Command, Option } from "commander";
-import { shellQuote } from "../../substrates/shell.js";
+import { shellArg } from "../../substrates/shell.js";
 import { computeStats, formatStatsHuman } from "../../run/stats.js";
 import { DEFAULT_EXPORT_MAX_BYTES, exportRun, formatExportHuman } from "../../feedback/export.js";
-import { cleanupRun, listRuns, readReview } from "../../run/stored-runs.js";
+import { listRuns, readReview } from "../../run/stored-runs.js";
 import { verifyRun } from "../../verify/verify.js";
 import { reclaimPreflightSandboxes, reclaimRunSandboxes, } from "../../run/reclaim.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 { plural } from "../../run/text.js";
+import { warnAndQueue } from "../deprecations.js";
+import { formatFindings, readRunFindings } from "../findings.js";
 export function registerRunCommand(parent, io) {
     addRunOptions(parent
         .command("run")
@@ -30,30 +32,40 @@ export function registerVerifyCommand(parent, io) {
         io.setExitCode(result.ok ? 0 : 2);
     });
 }
+const CLEANUP_RENAMED = "`cleanup` is now `reclaim --check`; `cleanup` is removed in 0.112.0.";
+/**
+ * The deprecated `cleanup`, hidden from help: one warning, then exactly `reclaim --check`, with
+ * its output and exit code. The old command read only what computer-use runs recorded and passed
+ * when it found no record; the check asks E2B.
+ */
 export function registerCleanupCommand(parent, io) {
     parent
-        .command("cleanup")
-        .description("Check a run's recorded resources and write cleanup.json. It stops nothing; humanish reclaim stops leftover sandboxes.")
-        .summary("Check that a run's resources were stopped.")
-        .option("--run <id>", RUN_OPTION_DESCRIPTION, "latest")
+        .command("cleanup", { hidden: true })
+        .description(`Deprecated: ${CLEANUP_RENAMED}`)
         .option("--cwd <path>", CWD_OPTION_DESCRIPTION, ".")
+        .option("--run <id>", RUN_OPTION_DESCRIPTION, "latest")
+        .option("--dotenv <path>", DOTENV_OPTION_DESCRIPTION)
+        .addOption(envFileAliasOption())
         .option("--json", JSON_OPTION_DESCRIPTION)
         .action(async (options, command) => {
-        const result = await cleanupRun(options.cwd, options.run);
-        writeResult(command, io, result, (value) => formatCleanupHuman(value, options.cwd));
-        io.setExitCode(result.ok ? 0 : 2);
+        warnAndQueue(command, io, CLEANUP_RENAMED);
+        await runReclaimCommand(io, command, { ...options, check: true });
     });
 }
 export function registerReviewCommand(parent, io) {
     parent
         .command("review")
-        .description("Show a run's review: verdict, summary and gaps.")
-        .summary("Build a review packet from verified run evidence.")
+        .description("Show a run's review: verdict, summary, gaps and the findings of its analysis, with the evidence each one cites.")
+        .summary("Show a run's outcome and analysis findings.")
         .option("--run <id>", RUN_OPTION_DESCRIPTION, "latest")
         .option("--cwd <path>", CWD_OPTION_DESCRIPTION, ".")
         .option("--json", JSON_OPTION_DESCRIPTION)
         .action(async (options, command) => {
-        const result = await readReview(options.cwd, options.run);
+        const review = await readReview(options.cwd, options.run);
+        // The verified run's exact id, so a run that moves `latest` meanwhile cannot swap the analysis.
+        const result = "verdict" in review
+            ? { ...review, analysis: await readRunFindings(options.cwd, review.runId) }
+            : review;
         writeResult(command, io, result, formatReviewHuman);
         io.setExitCode("ok" in result && result.ok === false ? 2 : 0);
     });
@@ -165,40 +177,57 @@ export function registerRuntimeCommands(parent, io) {
 export function registerReclaimCommand(parent, io) {
     parent
         .command("reclaim")
-        .description("Kill an interrupted run's sandboxes by the exact ids journaled in its sandbox-receipts.ndjson; never enumerates the E2B account. Needs E2B_API_KEY in the environment or in --dotenv.")
-        .summary("Stop an interrupted run's leftover sandboxes.")
+        .description("Kill an interrupted run's sandboxes: the exact ids journaled in its sandbox-receipts.ndjson, and any sandbox E2B lists with this run's owner tags (a sandbox whose id never reached a receipt). It lists only sandboxes that match every tag of this run. --check asks E2B whether each still exists and kills nothing. Needs E2B_API_KEY in the environment or in --dotenv.")
+        .summary("Stop or check an interrupted run's sandboxes.")
         .option("--cwd <path>", CWD_OPTION_DESCRIPTION, ".")
         .option("--run <id>", RUN_OPTION_DESCRIPTION, "latest")
         .addOption(new Option("--preflight", "Reclaim sandboxes left by interrupted `humanish study check` probes (journaled in .humanish/preflight) instead of a run's.").conflicts("run"))
+        .option("--check", "Ask E2B whether each sandbox still exists; kill nothing and write nothing. Exits 0 only when all are gone.")
         .option("--dotenv <path>", DOTENV_OPTION_DESCRIPTION)
         .addOption(envFileAliasOption())
         .option("--json", JSON_OPTION_DESCRIPTION)
-        .action(async (options, command) => {
-        // The kill calls read E2B_API_KEY from the environment: the env file, then discovered keys.
-        if (!(await applyEnvFileOption({
-            command,
-            cwd: options.cwd,
-            envFile: dotenvPathOf(options, command, io),
-            io,
-        })))
-            return;
-        const result = options.preflight
-            ? await reclaimPreflightSandboxes(options.cwd)
-            : await reclaimRunSandboxes(options.cwd, options.run);
-        writeResult(command, io, result, formatReclaimHuman);
-        io.setExitCode(result.ok ? 0 : 2);
-    });
+        .action((options, command) => runReclaimCommand(io, command, options));
+}
+/** `reclaim`, and the deprecated `cleanup`, which runs it with `check`. */
+async function runReclaimCommand(io, command, options) {
+    // The kill calls read E2B_API_KEY from the environment: the env file, then discovered keys.
+    if (!(await applyEnvFileOption({
+        command,
+        cwd: options.cwd,
+        envFile: dotenvPathOf(options, command, io),
+        io,
+    })))
+        return;
+    const hooks = { check: options.check === true };
+    const result = options.preflight
+        ? await reclaimPreflightSandboxes(options.cwd, hooks)
+        : await reclaimRunSandboxes(options.cwd, options.run, hooks);
+    writeResult(command, io, result, (value) => formatReclaimHuman(value, options.cwd, options.preflight === true));
+    io.setExitCode(result.ok ? 0 : 2);
+}
+/** The command that finishes what a reclaim left open, with --cwd when it was given. */
+function reclaimCommand(result, cwd, preflight) {
+    const target = preflight ? "--preflight" : `--run ${shellArg(result.runId)}`;
+    return `humanish reclaim ${target}${cwd === "." ? "" : ` --cwd ${shellArg(cwd)}`}`;
 }
-function formatReclaimHuman(result) {
+function formatReclaimHuman(result, cwd, preflight) {
     const lines = [];
-    lines.push(`Reclaim ${result.runId}: ${result.ok ? "ok" : "failed"}, ${plural(result.receiptCount, "sandbox receipt")}.`);
+    const check = result.mode === "check";
+    const search = result.tagSearch.status === "done"
+        ? `E2B lists ${plural(result.tagSearch.found, "more sandbox", "more sandboxes")} tagged with it`
+        : `E2B tag search ${result.tagSearch.status}`;
+    lines.push(`${check ? "Reclaim check" : "Reclaim"} ${result.runId}: ${result.state}. ${plural(result.receiptCount, "sandbox receipt")}; ${search}.`);
     for (const outcome of result.outcomes) {
-        lines.push(`  sandbox ${outcome.sandboxIdDigest} (${outcome.laneId}): ${outcome.state}${outcome.detail ? ` — ${outcome.detail}` : ""}`);
+        lines.push(`  sandbox ${outcome.sandboxIdDigest} (${outcome.laneId}, from ${outcome.source}): ${outcome.state}${outcome.detail ? `: ${outcome.detail}` : ""}`);
     }
     for (const warning of result.warnings)
         lines.push(`  warning: ${warning}`);
-    const stdout = lines.join("\n");
-    return result.error === undefined ? stdout : { stdout: `${stdout}\n`, error: result.error };
+    if (result.error === undefined && result.state !== "clean")
+        lines.push(result.state === "running"
+            ? `To stop them, run ${reclaimCommand(result, cwd, preflight)}.`
+            : `Run ${reclaimCommand(result, cwd, preflight)} again once E2B is reachable; each sandbox's create-time timeout is the backstop.`);
+    const stdout = `${lines.join("\n")}\n`;
+    return result.error === undefined ? stdout : { stdout, error: result.error };
 }
 const REVIEW_VERDICTS = {
     // A dry run, or a live run with no participant result; review's result does not carry the mode.
@@ -208,7 +237,10 @@ const REVIEW_VERDICTS = {
     blocked: "blocked",
     timed_out: "timed out",
 };
-/** A run's review: its verdict, summary and gaps, and where review.json is. */
+/**
+ * A run's review: its verdict, summary and gaps, its analysis findings, and where review.json is.
+ * A pass verdict on a run whose own ok is false leads with how the run ended (runDisplay), then why.
+ */
 function formatReviewHuman(result) {
     if (!("verdict" in result)) {
         // A run that did not pass verify has no review to show; verify says why.
@@ -225,12 +257,19 @@ function formatReviewHuman(result) {
             }
             : humanError(error);
     }
+    const verdict = REVIEW_VERDICTS[result.verdict];
+    const display = result.display;
+    const headline = result.verdict === "pass" && display !== undefined && display.state !== "passed"
+        ? `${display.label} (verdict pass)`
+        : verdict;
     return ([
-        `humanish review ${result.runId}: ${REVIEW_VERDICTS[result.verdict]}`,
+        `humanish review ${result.runId}: ${headline}`,
+        ...(display?.reason === undefined ? [] : [`why: ${display.reason}`]),
         "",
         result.summary,
         ...(result.gaps.length === 0 ? [] : ["", "gaps:", ...result.gaps.map((gap) => `- ${gap}`)]),
         "",
+        ...formatFindings(result.analysis),
         `review: ${result.path}`,
     ].join("\n") + "\n");
 }
@@ -246,6 +285,12 @@ function shareSafetyLines(result) {
         .filter((reason) => reason.code !== "VERIFY_FAILED")
         .map((reason) => `share-safety: ${reason.code}: ${reason.message}`);
 }
+/** For a run that is not finished, its liveness and sandbox state, so the line leads with them. */
+function unfinishedNote(result) {
+    return result.unfinished === undefined
+        ? ""
+        : ` (${result.unfinished.liveness}, sandboxes ${result.unfinished.sandboxes})`;
+}
 /**
  * One line for a pass. A failure lists only the failing checks. `--verbose` prints every check.
  * A run that does not exist prints only that.
@@ -254,12 +299,13 @@ function formatVerifyHuman(result) {
     if (result.error?.code === "HUMANISH_RUN_NOT_FOUND")
         return humanError(result.error);
     const runId = verifiedRunId(result);
+    const named = `${runId}${unfinishedNote(result)}`;
     const total = result.checks.length;
     const failed = result.checks.filter((check) => !check.ok);
     const lines = result.ok
-        ? [`verified ${runId} · ${result.shareSafety.status} · ${total} checks passed`]
+        ? [`verified ${named} · ${result.shareSafety.status} · ${total} checks passed`]
         : [
-            `verify failed: ${runId} · ${result.shareSafety.status} · ${failed.length} of ${total} checks failed`,
+            `verify failed: ${named} · ${result.shareSafety.status} · ${failed.length} of ${total} checks failed`,
             ...failed.map((check) => `- ${check.message}`),
         ];
     lines.push(...shareSafetyLines(result), ...result.warnings.map((warning) => `warning: ${warning}`));
@@ -273,43 +319,13 @@ function formatVerifyVerbose(result) {
         return humanError(result.error);
     return ([
         `humanish verify ${result.ok ? "passed" : "failed"}`,
-        `run: ${verifiedRunId(result)}`,
+        `run: ${verifiedRunId(result)}${unfinishedNote(result)}`,
         `share-safety: ${result.shareSafety.status}`,
         ...result.shareSafety.reasons.map((reason) => `share-safety reason: ${reason.code}: ${reason.message}`),
         ...result.checks.map((check) => `- ${check.ok ? "ok" : "fail"} ${check.name}: ${check.message}`),
         ...result.warnings.map((warning) => `warning: ${warning}`),
     ].join("\n") + "\n");
 }
-/** A command-line argument, single-quoted only when the shell would split or expand it. */
-function shellArg(value) {
-    return /^[\w@%+=:,./-]+$/.test(value) ? value : shellQuote(value);
-}
-/**
- * Cleanup only reads evidence and never stops a sandbox. A failed resource is an E2B sandbox not
- * recorded as stopped, which reclaim can stop from the run's sandbox receipts, so the last line
- * names it. A skipped resource is a provider reclaim does not handle, so it gets no line. `cwd` is
- * the --cwd the command was given, since cleanup's result masks it.
- */
-function reclaimPointer(result, cwd) {
-    if (result.runId === undefined || result.summary.failed === 0)
-        return [];
-    const cwdFlag = cwd === "." ? "" : ` --cwd ${shellArg(cwd)}`;
-    return [
-        `To stop leftover sandboxes, run humanish reclaim --run ${shellArg(result.runId)}${cwdFlag}.`,
-    ];
-}
-function formatCleanupHuman(result, cwd) {
-    if (!result.ok && result.error)
-        return humanError(result.error);
-    return ([
-        `humanish cleanup ${result.ok ? "passed" : "failed"}`,
-        `run: ${result.runId ?? result.run}`,
-        `resources: already-clean ${result.summary.alreadyClean}, skipped ${result.summary.skipped}, failed ${result.summary.failed}`,
-        ...(result.cleanupPath ? [`cleanup: ${result.cleanupPath}`] : []),
-        ...result.warnings.map((warning) => `warning: ${warning}`),
-        ...reclaimPointer(result, cwd),
-    ].join("\n") + "\n");
-}
 function formatRunsHuman(result) {
     if (!result.ok)
         return humanError(result.error);
@@ -318,6 +334,6 @@ function formatRunsHuman(result) {
     }
     return ([
         `latest: ${result.latest ?? "none"}`,
-        ...result.runs.map((run) => `- ${run.runId} ${run.mode ?? "unknown"} ${run.createdAt ?? "unknown"} ${run.path}`),
+        ...result.runs.map((run) => `- ${run.runId} ${run.mode ?? "unknown"} ${run.display?.label ?? "unreadable"} ${run.createdAt ?? "unknown"} ${run.path}`),
     ].join("\n") + "\n");
 }

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

@@ -9,6 +9,7 @@ import { cliAnalysisOptions } from "./analysis-signals.js";
 import { onRunShutdown } from "./run-signals.js";
 import { parseStudyCount, parseParticipantIds, parseObserverPort, wantsJson, writeResult, } from "../io.js";
 import { exposureRequestFromOptions, followObserver, planObserver, showObserver, staticObserverOpen, withObserverServer, } from "../observer-follow.js";
+import { writeRunFindings } from "../findings.js";
 import { formatCuaStudyHuman } from "./study-format.js";
 import { resolveRouteShouldOpen } from "./study-route-open.js";
 import { studyResultIdentity } from "../../run/study-result.js";
@@ -237,6 +238,7 @@ async function reportCuaRun(args, prepared, result, live) {
     }
     writeResult(args.command, args.io, output, formatCuaStudyHuman);
     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)) {
         const followResult = output.observer?.ok
             ? output.observer

package/dist/cli/commands/study-route-scripted.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 { formatScriptedStudyHuman } from "./study-format.js";
 import { observerOpen, resolveRouteShouldOpen, watchFinishedPlan } from "./study-route-open.js";
@@ -35,6 +36,7 @@ export function scriptedRouteRun(args) {
             const result = outcome.result;
             writeResult(args.command, args.io, result, formatScriptedStudyHuman);
             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.
             if (finishedPlan !== undefined && result.ok && result.observer !== undefined) {
                 await showObserver({

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

@@ -1,4 +1,5 @@
 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";

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 {
@@ -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()),
     };
 }
 /**
@@ -274,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

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