humanish 0.109.1 → 0.110.1

package/dist/cli/findings.js

@@ -0,0 +1,316 @@
+// 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";
+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 = `humanish 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. humanish 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.", `humanish 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.", `humanish 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.`, `humanish 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 = `humanish 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,11 +15,12 @@ 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. */

package/dist/cli/first-run-path.js

@@ -79,13 +79,16 @@ export function firstRunSteps(env) {
             : `${preferredAgent(env)?.label} (already signed in, so no API key is needed)`;
         // Everything the step needs, in one line. Splitting it across two commands means the second
         // one fails, which is the same dead end this guidance exists to remove.
+        if (!env.hasDesktopSdk && env.desktopPeerCommand === undefined) {
+            steps.push({
+                command: `${HUMANISH} doctor`,
+                why: "the hosted starter needs the desktop SDK, and installing it from here would remove what this directory's node_modules holds; doctor names the command to run from your project's directory",
+            });
+            return steps;
+        }
         const command = env.hasDesktopSdk
             ? `${HUMANISH} run try-live`
-            : env.installedInProject
-                ? `npm i -D @e2b/desktop && ${HUMANISH} run try-live`
-                : // Running from an npx cache: installing only the peer here would not be found, because
-                    // Node resolves it relative to humanish. Both, or neither.
-                    `npm i -D humanish @e2b/desktop && ${HUMANISH} run try-live`;
+            : `${env.desktopPeerCommand} && ${HUMANISH} run try-live`;
         steps.push({
             command,
             why: `a live study: one participant drives a real app in a hosted desktop, using ${brain}` +
@@ -99,7 +102,7 @@ export function firstRunSteps(env) {
     }
     steps.push({
         command: `${HUMANISH} keys set openai`,
-        why: "openai-computer-use needs an API key; to use a Codex or Claude Code login instead, sign in and change the study to actors[0].type: local-agent" +
+        why: "openai-computer-use needs an API key; to use a Codex or Claude Code login instead, sign in and change the study to actor.type: local-agent" +
             localUnavailable,
     });
     return steps;
@@ -134,8 +137,12 @@ export function agentsSection() {
         "humanish run local-browser # your loopback app; no E2B or model API key",
         "humanish run try-live      # demo app study: E2B plus the selected participant's authentication",
         "humanish verify --run latest --json   # is the evidence share-safe",
+        "humanish review --run <id>  # the run's outcome and its analysis findings",
         "```",
         "",
+        "- After a live run, run `humanish review --run <id>` (or `--json`) and report its findings to the",
+        "  person you are working for: each one's title, impact, confidence, recovery and cited captures.",
+        "  When it shows no findings, report its message and the command it names.",
         "- Studies are declared in `humanish/studies/*.yaml`. Edit `try-live.yaml`'s `subject` to point",
         "  at this project's own app once you have seen a run work.",
         "- Configure the local study without editing YAML: `humanish init --yes --local-browser",
@@ -144,7 +151,7 @@ export function agentsSection() {
         "  bundles into an issue; `humanish feedback issue` writes a redacted, share-safe draft.",
         "- `humanish tui` is for people and refuses to run in an agent session. Use the `--json`",
         "  commands above instead, and tell the person you are working for that `humanish tui` exists.",
-        "- A live run spends money. `execution.caps.maxUsd` in each study caps estimated model spend: the run",
+        "- A live run spends money. `caps.maxUsd` in each study caps estimated model spend: the run",
         "  stops before its next request once the estimate passes it, so the last request can go over, and",
         "  hosted desktop time is billed on top. Do not raise it without asking the person you are working for.",
         "",

package/dist/cli/io.d.ts

@@ -1,5 +1,5 @@
 import { Command, Option } from "commander";
-import { discoverProviderKeys } from "../keys/key-resolution.js";
+import { discoverProviderKeys, type DotenvLoad } from "../keys/key-resolution.js";
 import { type TelemetryProperties } from "./telemetry.js";
 import type { RunResult } from "../run/results.js";
 export declare const CLI_RESPONSE_SCHEMA = "humanish.cli-response.v1";
@@ -13,7 +13,18 @@ export interface CliIo {
 export declare const JSON_OPTION_DESCRIPTION = "Print a machine-readable JSON response.";
 export declare const CWD_OPTION_DESCRIPTION = "Project directory.";
 export declare const RUN_OPTION_DESCRIPTION = "Run id, or latest.";
-export declare const ENV_FILE_OPTION_DESCRIPTION = "Load unset variables from this env file. Values are never printed or saved.";
+export declare const DOTENV_OPTION_DESCRIPTION = "Load unset variables from this dotenv file. Values are never printed or saved.";
+/**
+ * The hidden `--env-file <path>` that `--dotenv` replaced. Node scans the whole argv for
+ * `--env-file` before a script runs, and stops only at `--` (src/node_dotenv.cc), so a missing file
+ * exits 9 through Node and never reaches humanish. `--dotenv` does not collide. Removed in 0.111.0.
+ */
+export declare function envFileAliasOption(): Option;
+/** The dotenv path a command was given: `--dotenv`, or the `--env-file` alias with its warning. */
+export declare function dotenvPathOf(options: {
+    dotenv?: string | undefined;
+    envFile?: string | undefined;
+}, command: Command, io: CliIo): string | undefined;
 export declare const PORT_OPTION_DESCRIPTION = "Port to listen on at 127.0.0.1.";
 /** `--port` for a loopback server whose default, 0, lets the OS pick a free port. */
 export declare function freePortOption(): Option;
@@ -22,6 +33,7 @@ export interface StudyCommandOptions {
     cwd: string;
     detach?: boolean | undefined;
     dryRun?: boolean | undefined;
+    dotenv?: string | undefined;
     envFile?: string | undefined;
     json?: boolean | undefined;
     open?: boolean | undefined;
@@ -50,13 +62,15 @@ export declare function applyEnvFileOption(args: {
     io: CliIo;
     env?: NodeJS.ProcessEnv;
     onDiscovered?: (names: string[]) => void;
+    /** Called with the dotenv path and the names it set, which were unset before. */
+    onLoaded?: (load: DotenvLoad) => void;
     /** False for the study-running commands, which discover only once the study resolves to live. */
     discoverKeys?: boolean;
 }): Promise<boolean>;
 /**
  * Provider-key discovery: fill still-missing keys from the documented project overlay, the
  * owning vendors' native stores, and the humanish user store. It is fill-only (an explicit
- * --env-file or process env always wins), and each fill is announced by name and source on
+ * --dotenv or process env always wins), and each fill is announced by name and source on
  * stderr, never by value. HUMANISH_STRICT_KEYS=1 restores env-only behavior.
  */
 export declare function discoverCliKeys(args: {

package/dist/cli/io.js

@@ -4,10 +4,10 @@ import { readFileSync } from "node:fs";
 import { dirname, resolve } from "node:path";
 import { fileURLToPath } from "node:url";
 import { Command, Option } from "commander";
-import { loadEnvFile } from "../keys/env-file.js";
+import { loadEnvFile, recordDotenvNames } from "../keys/env-file.js";
 import { discoverProviderKeys } from "../keys/key-resolution.js";
 import { deriveRunFacts } from "./telemetry.js";
-import { withQueuedWarnings } from "./deprecations.js";
+import { warnAndQueue, withQueuedWarnings } from "./deprecations.js";
 import { forTerminal } from "../routes/terminal/encoding.js";
 export const CLI_RESPONSE_SCHEMA = "humanish.cli-response.v1";
 function readCliVersion() {
@@ -23,7 +23,23 @@ export const CLI_VERSION = readCliVersion();
 export const JSON_OPTION_DESCRIPTION = "Print a machine-readable JSON response.";
 export const CWD_OPTION_DESCRIPTION = "Project directory.";
 export const RUN_OPTION_DESCRIPTION = "Run id, or latest.";
-export const ENV_FILE_OPTION_DESCRIPTION = "Load unset variables from this env file. Values are never printed or saved.";
+export const DOTENV_OPTION_DESCRIPTION = "Load unset variables from this dotenv file. Values are never printed or saved.";
+const ENV_FILE_RENAMED = "`--env-file` is now `--dotenv`; `--env-file` is removed in 0.111.0.";
+/**
+ * The hidden `--env-file <path>` that `--dotenv` replaced. Node scans the whole argv for
+ * `--env-file` before a script runs, and stops only at `--` (src/node_dotenv.cc), so a missing file
+ * exits 9 through Node and never reaches humanish. `--dotenv` does not collide. Removed in 0.111.0.
+ */
+export function envFileAliasOption() {
+    return new Option("--env-file <path>").hideHelp().conflicts("dotenv");
+}
+/** The dotenv path a command was given: `--dotenv`, or the `--env-file` alias with its warning. */
+export function dotenvPathOf(options, command, io) {
+    if (options.envFile === undefined)
+        return options.dotenv;
+    warnAndQueue(command, io, ENV_FILE_RENAMED);
+    return options.envFile;
+}
 export const PORT_OPTION_DESCRIPTION = "Port to listen on at 127.0.0.1.";
 /** `--port` for a loopback server whose default, 0, lets the OS pick a free port. */
 export function freePortOption() {
@@ -74,6 +90,8 @@ export async function applyEnvFileOption(args) {
         }
         for (const name of result.loaded)
             env[name] = stagedEnv[name];
+        recordDotenvNames(env, result.loaded);
+        args.onLoaded?.({ path: args.envFile, names: result.loaded });
     }
     if (args.discoverKeys !== false) {
         await discoverCliKeys({
@@ -88,7 +106,7 @@ export async function applyEnvFileOption(args) {
 /**
  * Provider-key discovery: fill still-missing keys from the documented project overlay, the
  * owning vendors' native stores, and the humanish user store. It is fill-only (an explicit
- * --env-file or process env always wins), and each fill is announced by name and source on
+ * --dotenv or process env always wins), and each fill is announced by name and source on
  * stderr, never by value. HUMANISH_STRICT_KEYS=1 restores env-only behavior.
  */
 export async function discoverCliKeys(args) {

package/dist/cli/product-sentence.d.ts

@@ -1,6 +1,6 @@
 /**
- * The product in one sentence. Line 3 of `README.md`, package.json's description, `humanish --help`,
- * bare `humanish` and the humanish skill all use it; tests/cli/product-sentence.test.ts holds them
- * equal.
+ * The product in one sentence. package.json's description, `humanish --help` and bare `humanish`
+ * use it, and line 3 of `README.md` and the humanish skill's description open with it;
+ * tests/cli/product-sentence.test.ts holds them equal.
  */
 export declare const PRODUCT_SENTENCE = "Synthetic user research for apps, CLIs, and agent-facing product flows.";

package/dist/cli/product-sentence.js

@@ -1,6 +1,6 @@
 /**
- * The product in one sentence. Line 3 of `README.md`, package.json's description, `humanish --help`,
- * bare `humanish` and the humanish skill all use it; tests/cli/product-sentence.test.ts holds them
- * equal.
+ * The product in one sentence. package.json's description, `humanish --help` and bare `humanish`
+ * use it, and line 3 of `README.md` and the humanish skill's description open with it;
+ * tests/cli/product-sentence.test.ts holds them equal.
  */
 export const PRODUCT_SENTENCE = "Synthetic user research for apps, CLIs, and agent-facing product flows.";

package/dist/comms/receiving-runtime.js

@@ -29,7 +29,7 @@ export async function resolveReceivingConnection(cwd, name, env, keyDeps) {
     });
     const apiKey = resolved[connection.apiKeyEnv]?.trim();
     if (!apiKey)
-        throw new Error("Email connection credential is missing. Add it in Connections, or provide the configured key with --env-file.");
+        throw new Error("Email connection credential is missing. Add it in Connections, or provide the configured key with --dotenv.");
     return { connection, apiKey, adapter: createReceivingAdapter(connection, apiKey) };
 }
 export async function prepareReceivingRun(args) {

package/dist/comms/setup.js

@@ -53,7 +53,7 @@ export async function checkCommsConnection(args) {
                 ...base,
                 ready: false,
                 code: "credential_missing",
-                message: "The configured credential is missing. Add it in Connections or provide it with --env-file.",
+                message: "The configured credential is missing. Add it in Connections or provide it with --dotenv.",
             };
         base.credentialPresent = true;
         if (!args.online)

package/dist/evidence/redaction.d.ts

@@ -7,10 +7,14 @@ export declare function containsSensitive(text: string): boolean;
  * passes only this value at a sandbox-id key.
  */
 export declare const REDACTED_SANDBOX_ID = "[redacted-sandbox-id]";
+/** A sandbox id's public stand-in: its digest matches a receipt without naming the sandbox. */
+export declare function sandboxIdDigest(id: string): string;
+/** The raw ids at the keys redactSandboxIds replaces, anywhere in `value`. */
+export declare function collectSandboxIds(value: unknown, into?: Set<string>): Set<string>;
 /**
- * `value` with every sandbox id replaced by REDACTED_SANDBOX_ID: strings at `sandboxId` and
- * `subjectSandboxId`, and the `id` of each `providerResources` entry. A run keeps raw ids as local
- * evidence for cleanup; a copy made to be shared names no sandbox.
+ * `value` with every sandbox id replaced by REDACTED_SANDBOX_ID plus its digest: strings at
+ * `sandboxId` and `subjectSandboxId`, and the `id` of each `providerResources` or `resources` entry. Raw ids live
+ * only in a run's sandbox-receipts.ndjson; every record and output names a sandbox by digest.
  */
 export declare function redactSandboxIds(value: unknown): unknown;
 /** Redact secrets to [REDACTED_SECRET] and local paths to their path labels. */