humanish 0.110.0 → 0.110.2

package/dist/cli/doctor.js

@@ -1,12 +1,16 @@
-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 { detectLocalAgents, localAgentDoctorMessage, localAgentReady, 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";
+import { cli } from "./invocation.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
@@ -16,7 +20,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 +35,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,12 +95,13 @@ export async function doctor(cwdInput, options = {}) {
         await desktopSdkCheck(setup),
         terminalSurfaceCheck(),
         ...localAgentChecks(agents),
+        await claudeTranscriptCheck(env),
         ...keyChecks(probes, receivingKey, setup, keyUsers),
         ...(setup?.checks ?? [
             {
                 name: "setup route",
                 ok: true,
-                message: "General capabilities only. Use humanish doctor --study <study> for the selected participant's requirements and separate analysis readiness.",
+                message: `General capabilities only. Use ${cli("doctor --study <study>")} for the selected participant's requirements and separate analysis readiness.`,
             },
         ]),
     ];
@@ -164,7 +174,7 @@ async function sourceCheck(projectRoot) {
         ok,
         message: ok
             ? "committed humanish/ source directory is present and safe to read"
-            : "no readable humanish/ source directory; run humanish init --yes",
+            : `no readable humanish/ source directory; run ${cli("init --yes")}`,
     };
 }
 async function runtimeIgnoreCheck(projectRoot) {
@@ -174,7 +184,7 @@ async function runtimeIgnoreCheck(projectRoot) {
         ok,
         message: ok
             ? ".gitignore lists .humanish/"
-            : ".gitignore does not list .humanish/; run humanish init --yes",
+            : `.gitignore does not list .humanish/; run ${cli("init --yes")}`,
     };
 }
 /**
@@ -205,7 +215,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()),
     };
 }
 /**
@@ -262,7 +272,9 @@ async function probeDoctorKeys(cwd, env, study, keyDeps, dotenv) {
  * The operator's own coding agents, one row each, reported as a capability and never a gate: a
  * machine with none is not broken, it just needs a provider key. These rows exist because "go make
  * an API key" is where most people trying humanish stop, and a developer very often already has one
- * of these signed in. An agent that is installed but not signed in is a note.
+ * of these signed in. An agent that cannot run participants (not signed in under the participant's
+ * environment, sign-in unknown, or a Claude Code below the floor) is a note; `--study` fails on it
+ * when the study selects that agent.
  */
 function localAgentChecks(agents) {
     if (agents.length === 0)
@@ -270,10 +282,39 @@ function localAgentChecks(agents) {
     return agents.map((agent) => ({
         name: `local agent ${agent.bin}`,
         ok: true,
-        ...(agent.authStatus === "authenticated" ? {} : { status: "note" }),
+        ...(localAgentReady(agent) ? {} : { status: "note" }),
         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 {};

package/dist/cli/findings.js

@@ -0,0 +1,317 @@
+// A run's analysis findings for `review`, `analyze show` and the end of a live `run`: the
+// `humanish.analysis-findings.v1` projection and its text. The analysis artifact stays the record;
+// this reads the version `analyze show` selects and never starts an analysis.
+import path from "node:path";
+import { DEFAULT_ANALYSIS_MAX_COST_USD } from "../analysis/automatic-config.js";
+import { loadAnalysis } from "../analysis/load.js";
+import { projectShareCheckedAnalysis } from "../analysis/sharing.js";
+import { loadRunBundlePrepared, resolveRunPath } from "../run/locate.js";
+import { resolvePhysicalCwd, runIdOf } from "../run/paths.js";
+import { plural } from "../run/text.js";
+import { shellQuote } from "../substrates/shell.js";
+import { analysisOutcomeText, wantsJson } from "./io.js";
+import { cli } from "./invocation.js";
+export const ANALYSIS_FINDINGS_SCHEMA = "humanish.analysis-findings.v1";
+/** ` --cwd <dir>`, or "" when `cwd` is the current directory. */
+function cwdFlag(cwd) {
+    if (path.resolve(cwd) === process.cwd())
+        return "";
+    return ` --cwd ${/^[\w@%+=:,./-]+$/.test(cwd) ? cwd : shellQuote(cwd)}`;
+}
+function analyzeCommand(source, provider) {
+    const run = cli(`analyze --run ${source.runId}${source.cwdFlag}`);
+    return provider === "codex"
+        ? `${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);
+        }
+    const byId = new Map(analysis.evidence.map((entry) => [entry.id, entry]));
+    return [...bases].flatMap(([id, used]) => {
+        const entry = byId.get(id);
+        if (!entry)
+            return [];
+        return [
+            {
+                id,
+                streamId: entry.streamId,
+                kind: entry.kind,
+                bases: [...used],
+                frame: entry.frame,
+                elapsedMs: entry.elapsedMs,
+                at: entry.at,
+                capture: entry.capture ? path.join(runRoot, entry.capture.path) : null,
+            },
+        ];
+    });
+}
+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,
+        title: finding.title,
+        summary: finding.summary,
+        impact: finding.impact,
+        confidence: finding.confidence,
+        recovery: finding.recovery,
+        affected: finding.affectedStreamIds.map((streamId) => ({
+            streamId,
+            label: labels.get(streamId) ?? streamId,
+        })),
+        exposedCount: finding.exposedStreamIds.length,
+        evidence: evidenceOf(finding, loaded.analysis, runRoot),
+        nextStep: finding.nextStep,
+        correction: correction
+            ? {
+                status: correction.status,
+                reason: correction.reason,
+                replacementClaim: correction.replacementClaim,
+            }
+            : null,
+    };
+}
+/** A view with no findings: what happened and the command that gets them. */
+function withoutFindings(source, state, reason, message, next) {
+    return {
+        schema: ANALYSIS_FINDINGS_SCHEMA,
+        runId: source.runId,
+        state,
+        reason,
+        message,
+        next,
+        analysisId: null,
+        status: null,
+        provider: null,
+        model: null,
+        completedAt: null,
+        estimatedCostUsd: null,
+        runPath: source.runRoot || null,
+        path: null,
+        summary: null,
+        findings: [],
+        limitations: [],
+        warnings: source.loaded.warnings,
+    };
+}
+/** The findings view of a run's selected analysis, or why it has none. */
+export function analysisFindings(source) {
+    if (source.mode !== undefined && source.mode !== "live")
+        return withoutFindings(source, "dry_run", null, "This is a dry run: no participant used the product, so there is nothing to analyze. Findings come from live runs.", null);
+    const loaded = projectShareCheckedAnalysis(source.loaded);
+    const analysis = loaded.analysis;
+    if (analysis?.result && (loaded.state === "ready" || loaded.state === "stale")) {
+        const result = analysis.result;
+        const stale = loaded.state === "stale";
+        return {
+            schema: ANALYSIS_FINDINGS_SCHEMA,
+            runId: source.runId,
+            state: loaded.state,
+            reason: stale ? (loaded.warnings[0] ?? null) : null,
+            message: stale
+                ? `The run's evidence changed after analysis ${analysis.id}, so its findings may not match the run.`
+                : `Analysis ${analysis.id} is ${analysis.status}, with ${plural(result.findings.length, "finding")}.`,
+            next: stale ? analyzeCommand(source, analysis.provider) : null,
+            analysisId: analysis.id,
+            status: analysis.status,
+            provider: analysis.provider,
+            model: analysis.config.model,
+            completedAt: analysis.completedAt,
+            estimatedCostUsd: analysis.usage.estimatedCostUsd,
+            runPath: source.runRoot,
+            path: path.join(source.runRoot, "analysis", analysis.id, "analysis.json"),
+            summary: result.summary,
+            findings: result.findings.map((finding) => findingView(finding, { ...loaded, analysis }, source.runRoot)),
+            limitations: result.limitations,
+            warnings: loaded.warnings,
+        };
+    }
+    if (loaded.warnings.includes("ANALYSIS_SENSITIVE_TEXT_QUARANTINED"))
+        return withoutFindings(source, "unavailable", "ANALYSIS_SENSITIVE_TEXT_QUARANTINED", `The analysis text matched a sensitive-text pattern, so it is not printed. ${cli(`analyze show --run ${source.runId}${source.cwdFlag} --json`)} prints the raw record.`, null);
+    const job = loaded.automatic;
+    if (job?.state === "queued" || job?.state === "running")
+        return withoutFindings(source, "running", null, "The automatic analysis is still running. Check again when it finishes.", cli(`review --run ${source.runId}${source.cwdFlag}`));
+    if (analysis && analysis.result === null)
+        return withoutFindings(source, "failed", analysis.error, `Analysis attempt ${analysis.id} ${analysis.status === "cancelled" ? "was cancelled" : "failed"}${analysis.error ? ` (${analysis.error})` : ""} and left no findings.`, analyzeCommand(source, analysis.provider));
+    if (job?.state === "failed" || job?.state === "cancelled") {
+        const outcome = analysisOutcomeText(job);
+        return withoutFindings(source, "failed", job.reason, `The automatic analysis ${outcome.startsWith("failed") ? "" : "was "}${outcome}.`, analyzeCommand(source, job.reason === "AUTOMATIC_ANALYSIS_CODEX_UNAVAILABLE" ? "codex" : undefined));
+    }
+    if (job?.state === "skipped") {
+        const refused = job.reason === "AUTOMATIC_ANALYSIS_ADMISSION_REFUSED";
+        return withoutFindings(source, "skipped", job.reason, `The automatic analysis was ${analysisOutcomeText(job)}.${refused ? " The dry run prints its cost estimate; run it again with a --max-cost above the estimate." : ""}`, job.reason === "AUTOMATIC_ANALYSIS_NO_PARTICIPANT_EVIDENCE"
+            ? null
+            : `${analyzeCommand(source, undefined)}${refused ? " --dry-run" : ""}`);
+    }
+    if (job !== undefined || loaded.state === "invalid")
+        return withoutFindings(source, "unavailable", job?.reason ?? loaded.warnings[0] ?? null, "This run's analysis records could not be read or checked, so no findings are shown.", cli(`analyze list --run ${source.runId}${source.cwdFlag}`));
+    return withoutFindings(source, "none", null, "No analysis has run for this run.", analyzeCommand(source, undefined));
+}
+/**
+ * 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 async function readRunAnalysis(cwd, run, analysisId) {
+    const physical = await resolvePhysicalCwd(cwd);
+    const prepared = await resolveRunPath(physical, run).catch(() => null);
+    if (!prepared)
+        return null;
+    const bundle = await loadRunBundlePrepared(physical, prepared).catch(() => null);
+    return {
+        runId: runIdOf(prepared),
+        mode: bundle?.bundle.mode,
+        runRoot: prepared.relativeRunRoot,
+        loaded: await loadAnalysis(prepared, analysisId),
+        cwdFlag: cwdFlag(cwd),
+    };
+}
+/** The view of a run that could not be found. */
+export function missingRunFindings(cwd, run) {
+    const loaded = {
+        state: "invalid",
+        analysis: null,
+        corrections: [],
+        warnings: ["ANALYSIS_RUN_NOT_FOUND"],
+    };
+    const flag = cwdFlag(cwd);
+    return withoutFindings({ runId: run, mode: undefined, runRoot: "", loaded, cwdFlag: flag }, "unavailable", "ANALYSIS_RUN_NOT_FOUND", `Run ${run} was not found or its storage is unsafe.`, cli(`runs${flag}`));
+}
+/** The findings of a run's selected analysis, or why it has none. */
+export async function readRunFindings(cwd, run, analysisId) {
+    const source = await readRunAnalysis(cwd, run, analysisId);
+    return source ? analysisFindings(source) : missingRunFindings(cwd, run);
+}
+const IMPACT_TEXT = {
+    blocked_task: "blocked task",
+    friction: "friction",
+    recovery: "recovery",
+    uncertain: "uncertain",
+};
+const RECOVERY_TEXT = {
+    recovered: "recovered",
+    not_observed: "no recovery observed",
+    unknown: "recovery unknown",
+};
+/** `+1:05` from milliseconds since the first retained capture. */
+function elapsedText(ms) {
+    const seconds = Math.floor(ms / 1000);
+    const minutes = Math.floor(seconds / 60);
+    const hours = Math.floor(minutes / 60);
+    const ss = String(seconds % 60).padStart(2, "0");
+    return hours > 0
+        ? `+${hours}:${String(minutes % 60).padStart(2, "0")}:${ss}`
+        : `+${minutes}:${ss}`;
+}
+/** One participant's cited moments: each frame once, at its earliest cited time. */
+function momentsText(evidence) {
+    const frames = new Map();
+    let unframed = 0;
+    for (const entry of evidence) {
+        if (entry.frame === null) {
+            unframed++;
+            continue;
+        }
+        const earlier = frames.get(entry.frame);
+        if (earlier === undefined ||
+            (entry.elapsedMs !== null && (earlier ?? Infinity) > entry.elapsedMs))
+            frames.set(entry.frame, entry.elapsedMs);
+    }
+    const parts = [...frames]
+        .sort(([a], [b]) => a - b)
+        .map(([frame, ms]) => `frame ${frame}${ms === null ? "" : ` at ${elapsedText(ms)}`}`);
+    if (unframed > 0)
+        parts.push(`${plural(unframed, "item")} with no frame`);
+    return parts.join(", ");
+}
+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 correction = finding.correction;
+    return [
+        `${finding.id} ${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")}`,
+        ...streams.map((streamId) => {
+            const moments = momentsText(finding.evidence.filter((entry) => entry.streamId === streamId));
+            const label = `${labels.get(streamId) ?? streamId}${labels.has(streamId) ? "" : " (cited, not affected)"}`;
+            return `   - ${label}${moments ? `: ${moments}` : ""}`;
+        }),
+        ...(captures.length === 0 ? [] : [`   captures: ${captures.join(", ")}`]),
+        `   next step: ${finding.nextStep}`,
+        ...(correction === null
+            ? []
+            : [
+                `   human review: ${correction.status}, ${correction.reason}${correction.replacementClaim ? ` Amended claim: ${correction.replacementClaim}` : ""}`,
+            ]),
+    ];
+}
+/** 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")
+        return [`findings: none. ${view.message}`, ...(view.next ? [`next: ${view.next}`] : [])];
+    const model = [view.provider, view.model].filter(Boolean).join(" ");
+    const cost = view.estimatedCostUsd === null ? "" : `, estimated $${view.estimatedCostUsd.toFixed(2)}`;
+    return [
+        `findings: ${view.findings.length} from analysis ${view.analysisId} (${view.status}, ${model}${cost})`,
+        ...(view.state === "stale" ? [`warning: ${view.message}`, `next: ${view.next}`] : []),
+        ...(view.summary ? [view.summary] : []),
+        ...view.findings.flatMap((finding) => ["", ...findingLines(finding, view.runPath ?? "")]),
+        ...(view.limitations.length === 0
+            ? []
+            : ["", "limitations:", ...view.limitations.map((limitation) => `- ${limitation}`)]),
+        ...view.warnings.map((warning) => `warning: ${warning}`),
+        "",
+        `analysis: ${view.path}`,
+    ];
+}
+/** At most `limit` findings, one line each, and the command that prints all of them. */
+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);
+    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}`),
+        ...(view.findings.length > limit
+            ? [`- and ${plural(view.findings.length - limit, "more finding")}`]
+            : []),
+        `all findings: ${fullCommand}`,
+    ];
+}
+/**
+ * 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 async function writeRunFindings(command, io, cwd, result) {
+    const outcome = result.automaticAnalysis;
+    const analysisId = outcome?.result?.analysisId;
+    if (wantsJson(command) ||
+        result.runId === undefined ||
+        analysisId === undefined ||
+        (outcome?.state !== "complete" && outcome?.state !== "partial"))
+        return;
+    try {
+        const view = await readRunFindings(cwd, result.runId, analysisId);
+        const full = cli(`review --run ${view.runId}${cwdFlag(cwd)}`);
+        io.writeOut(`${formatFindingsSummary(view, full).join("\n")}\n`);
+    }
+    catch {
+        // The run's own result is already printed; review reads the same record later.
+    }
+}

package/dist/cli/first-run-path.d.ts

@@ -15,19 +15,35 @@ export interface FirstRunEnvironment {
      */
     hasDesktopSdk: boolean;
     /**
-     * Whether humanish itself is installed in this project rather than running from an npx cache.
-     * It changes what advice is true: a one-shot `npx humanish` resolves its optional peer relative
-     * to itself, so "install the peer here" cannot work; humanish has to be installed alongside it.
+     * The command that installs `@e2b/desktop` where this humanish resolves it, ahead of
+     * `npx humanish`: beside humanish in its project, or humanish and the peer together in this one
+     * when humanish runs from an npx cache, a global install or another directory. Undefined where
+     * `npm i` would prune a node_modules that no package.json declares.
      */
-    installedInProject: boolean;
+    desktopPeerCommand: string | undefined;
     /** A provider API key for the model. */
     hasProviderKey: boolean;
     /** The coding agents already signed in locally: Codex, Claude Code, or both. */
     localAgents: readonly SignedInAgent[];
-    /** Host shape only; `doctor --study local-browser` owns exact read-only readiness. */
+    /**
+     * init's quick read of this host for a local browser study: Linux x64 with `/dev/kvm`,
+     * `/dev/net/tun` and Docker,
+     * or an M3-or-newer Mac. Undefined when it was not read. `doctor --study local-browser` owns the
+     * full check.
+     */
+    localBrowserHost?: LocalBrowserHost;
+    /** Host shape only, for the prerequisites a local step names. */
     platform?: NodeJS.Platform;
-    arch?: string;
+    /** How a suggested command invokes humanish; `npx humanish` when unset. */
+    humanish?: string;
 }
+/** Whether this host passed init's quick checks for a local browser study, and why not. */
+export type LocalBrowserHost = {
+    ok: true;
+} | {
+    ok: false;
+    reason: string;
+};
 export type FirstRunActor = "openai-computer-use" | "local-agent";
 /**
  * Which brain the starter live study should be written for. A machine with a signed-in coding agent
@@ -40,7 +56,7 @@ export declare function starterActorFor(env: FirstRunEnvironment): FirstRunActor
  * refuse to run on a machine where only Claude Code is signed in.
  */
 export declare function starterLocalAgentFor(env: FirstRunEnvironment): LocalAgentId | undefined;
-/** Hosts that run local browser studies: Linux x64 and Apple Silicon Macs. */
+/** Host shapes the local browser route is built for: Linux x64 and Apple Silicon Macs. */
 export declare function supportsLocalBrowser(platform: NodeJS.Platform | undefined, arch: string | undefined): boolean;
 export interface FirstRunStep {
     /** The exact command to run. */
@@ -49,14 +65,18 @@ export interface FirstRunStep {
     why: string;
 }
 /**
- * The next one or two commands, in order. Deliberately short: a list of twelve options is the same
- * as no guidance, and the reader here has just been handed twenty files.
+ * The next two or three commands, in order: the dry run, the hosted try-live study when keys or a
+ * signed-in agent allow it, and the local browser study where this host passed its quick checks.
+ * Deliberately short: a list of twelve options is the same as no guidance, and the reader here has
+ * just been handed a directory of new files.
  */
 export declare function firstRunSteps(env: FirstRunEnvironment): FirstRunStep[];
 /** The block init prints after its changes. */
 export declare function firstRunGuidance(env: FirstRunEnvironment): string[];
-/** Lets init recognise its own section without rewriting a file someone else wrote. */
+/** Starts humanish's section of `AGENTS.md`, on its heading line. */
 export declare const AGENTS_SECTION_MARKER = "<!-- humanish:agents-guide -->";
+/** Ends humanish's section, so init can replace the section and nothing after it. */
+export declare const AGENTS_SECTION_END_MARKER = "<!-- /humanish:agents-guide -->";
 /**
  * What the next coding agent needs to know about humanish in this project.
  *
@@ -64,6 +84,7 @@ export declare const AGENTS_SECTION_MARKER = "<!-- humanish:agents-guide -->";
  * read on arrival. Increasingly the thing that ran `humanish init` was itself an agent working for
  * someone, and the agent that shows up tomorrow finds a `humanish/` directory with no idea what it
  * is for. Deliberately short and command-first, because an agent acts on the commands it is given.
+ * Commands use `humanish`, the prefix init chose for where humanish is installed.
  */
-export declare function agentsSection(): string;
+export declare function agentsSection(humanish?: string): string;
 export {};