humanish 0.110.0 → 0.110.2

package/dist/cli/commands/runs.js

@@ -1,14 +1,17 @@
 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";
+import { cli } from "../invocation.js";
 export function registerRunCommand(parent, io) {
     addRunOptions(parent
         .command("run")
@@ -30,30 +33,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);
     });
@@ -150,7 +163,7 @@ export function registerRuntimeCommands(parent, io) {
             catch (error) {
                 const message = error instanceof Error
                     ? error.message
-                    : "Local runtime setup failed. Run humanish runtime setup to retry.";
+                    : `Local runtime setup failed. Run ${cli("runtime setup")} to retry.`;
                 const result = {
                     schema: "humanish.runtime-result.v1",
                     ok: false,
@@ -165,50 +178,96 @@ 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 cli(`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(result.reason === "dry-run"
+        ? `${check ? "Reclaim check" : "Reclaim"} ${result.runId}: ${result.state}. It was a dry run, which creates no sandboxes, so E2B was not contacted.`
+        : `${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 NOTHING_TESTED = "no product behavior was tested";
 const REVIEW_VERDICTS = {
     // A dry run, or a live run with no participant result; review's result does not carry the mode.
-    contract_proof_only: "no verdict; no product behavior was tested",
+    contract_proof_only: `no verdict; ${NOTHING_TESTED}`,
     pass: "pass",
     fail: "fail",
     blocked: "blocked",
     timed_out: "timed out",
 };
-/** A run's review: its verdict, summary and gaps, and where review.json is. */
+/** The state runDisplay gives a finished run whose own ok agrees with its verdict. */
+const VERDICT_STATES = {
+    pass: "passed",
+    fail: "failed",
+    blocked: "blocked",
+    timed_out: "timed_out",
+};
+/**
+ * Review's headline: the run's display label, as `humanish runs`, review.md and the Observer show
+ * it. A verdict that names another state follows in parentheses, so an interrupted run whose last
+ * flush judged its participants `fail` reads "interrupted (verdict fail)". A run with no display,
+ * which verify does not pass, falls back to the verdict.
+ */
+function reviewHeadline(verdict, display) {
+    if (display === undefined)
+        return REVIEW_VERDICTS[verdict];
+    if (display.state === "no_verdict" || display.state === "dry_run")
+        return `${display.label}; ${NOTHING_TESTED}`;
+    const judged = VERDICT_STATES[verdict];
+    return judged === undefined || judged === display.state
+        ? display.label
+        : `${display.label} (verdict ${REVIEW_VERDICTS[verdict]})`;
+}
+/**
+ * A run's review: how it ended (runDisplay) and why it failed when it says, its summary and gaps,
+ * its analysis findings, and where review.json is.
+ */
 function formatReviewHuman(result) {
     if (!("verdict" in result)) {
         // A run that did not pass verify has no review to show; verify says why.
@@ -220,17 +279,20 @@ function formatReviewHuman(result) {
             ? {
                 error: {
                     ...error,
-                    message: `${error.message} humanish verify --run ${result.run} shows why.`,
+                    message: `${error.message} ${cli(`verify --run ${result.run}`)} shows why.`,
                 },
             }
             : humanError(error);
     }
+    const display = result.display;
     return ([
-        `humanish review ${result.runId}: ${REVIEW_VERDICTS[result.verdict]}`,
+        `humanish review ${result.runId}: ${reviewHeadline(result.verdict, display)}`,
+        ...(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 +308,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,18 +322,19 @@ 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}`));
     const cwdFlag = result.cwd === process.cwd() ? "" : ` --cwd ${result.cwd}`;
     if (!result.ok)
-        lines.push(`every check: humanish verify --run ${runId}${cwdFlag} --verbose`);
+        lines.push(`every check: ${cli(`verify --run ${runId}${cwdFlag} --verbose`)}`);
     return `${lines.join("\n")}\n`;
 }
 function formatVerifyVerbose(result) {
@@ -273,43 +342,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 +357,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/setup.js

@@ -6,6 +6,7 @@ import { buildPayload, disabledByEnvironment, readTelemetryState, telemetryState
 import { doctor } from "../doctor.js";
 import { applyEnvFileOption, CLI_VERSION, CWD_OPTION_DESCRIPTION, DOTENV_OPTION_DESCRIPTION, dotenvPathOf, envFileAliasOption, JSON_OPTION_DESCRIPTION, markInvocationEnvelopeWritten, wantsJson, writeResult, formatCliError, } from "../io.js";
 import { plural } from "../../run/text.js";
+import { cli } from "../invocation.js";
 export function registerInitCommand(parent, io) {
     parent
         .command("init")
@@ -283,7 +284,7 @@ export function registerKeysCommand(parent, io) {
             store: storePath,
             names,
             message: names.length === 0
-                ? "The store is empty. Add a key with `humanish keys set <vendor>`."
+                ? `The store is empty. Add a key with \`${cli("keys set <vendor>")}\`.`
                 : `${plural(names.length, "key name")} stored. Values are never printed.`,
         };
         writeResult(command, io, result, formatKeysHuman);
@@ -304,19 +305,27 @@ function formatInitHuman(result) {
     const title = result.ok ? `humanish init ${result.mode}` : `humanish init ${result.mode} blocked`;
     const lines = [title, `cwd: ${result.cwd}`];
     if (result.ok && result.mode === "applied") {
-        // A successful setup should leave its next action on the first terminal screen.
-        // Dry-runs and refusals retain their full plan; JSON always retains every change.
-        const counts = new Map();
-        for (const change of result.changes) {
-            counts.set(change.action, (counts.get(change.action) ?? 0) + 1);
-        }
-        const labels = {
-            create: "created",
-            mkdir: "directories prepared",
-            update: "updated",
-            skip: "preserved",
-        };
-        lines.push("", `changes: ${[...counts].map(([action, count]) => `${count} ${labels[action]}`).join(", ")}`, "Use humanish init --dry-run --json to inspect all files.");
+        // Name each file init wrote, so the person or agent who ran it can review exactly those
+        // files; directories and preserved files are counts. JSON always carries every change.
+        const files = (action) => result.changes.filter((change) => change.action === action && change.target !== "runtime");
+        const created = files("create");
+        const updated = files("update");
+        const preserved = result.changes.filter((change) => change.action === "skip").length;
+        const directories = result.changes.filter((change) => change.action === "mkdir").length;
+        lines.push("");
+        if (created.length > 0)
+            lines.push("created:", ...created.map((change) => `  ${change.path}`));
+        if (updated.length > 0)
+            lines.push("updated:", ...updated.map((change) => `  ${change.path} (${change.reason})`));
+        if (created.length === 0 && updated.length === 0)
+            lines.push("no files changed");
+        if (preserved > 0 || directories > 0)
+            lines.push([
+                ...(preserved > 0 ? [`${plural(preserved, "existing path")} unchanged`] : []),
+                ...(directories > 0
+                    ? [`${plural(directories, "ignored directory", "ignored directories")} prepared`]
+                    : []),
+            ].join(", "));
     }
     else {
         lines.push("", "changes:", ...result.changes.map(formatInitChange));

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

@@ -8,7 +8,8 @@ import { ServeTunnelError } from "../../observer/tunnel.js";
 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 { exposureRequestFromOptions, followDecision, 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";
@@ -86,7 +87,9 @@ function resolveCuaSettings(args) {
     }
     const dryRun = resolveStudyDryRun(args.config, args.options.dryRun, true) ?? true;
     const port = parseObserverPort(args.options.port ?? "0");
-    const wantsFollow = args.mode === "watch" && !wantsMachine && args.options.detach !== true && dryRun !== true;
+    const wantsFollow = args.mode === "watch" &&
+        dryRun !== true &&
+        followDecision({ wantsMachine, detach: args.options.detach, serve: args.options.serve }).follow;
     if (port === null) {
         refuseCua(args, dryRun, "HUMANISH_WATCH_OPTION_CONFLICT", "--port must be an integer between 0 and 65535.");
         return undefined;
@@ -99,7 +102,8 @@ function prepareCuaWatch(args, settings) {
     // one surface that serves runtime E2B stream URLs, so it must sit behind edge auth.
     const exposeValidation = validateExposure("watch", exposureRequestFromOptions(args.options), {
         dryRun: settings.dryRun,
-        detach: args.options.detach === true,
+        // A watch that will not follow, because of --detach or no interactive terminal, cannot expose.
+        detach: args.options.detach === true || (!settings.wantsMachine && !settings.wantsFollow),
         json: settings.wantsMachine,
     });
     if (!exposeValidation.ok) {
@@ -116,6 +120,7 @@ function prepareCuaWatch(args, settings) {
             port: args.options.port ?? "0",
             open: settings.shouldOpen,
             ...(args.options.detach === undefined ? {} : { detach: args.options.detach }),
+            ...(args.options.serve === undefined ? {} : { serve: args.options.serve }),
         })
         : undefined;
     if (finishedPlan === null)
@@ -237,6 +242,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-open.js

@@ -27,6 +27,7 @@ export function watchFinishedPlan(args, wantsMachine, shouldOpen) {
         port: args.options.port ?? "0",
         open: shouldOpen,
         ...(args.options.detach === undefined ? {} : { detach: args.options.detach }),
+        ...(args.options.serve === undefined ? {} : { serve: args.options.serve }),
     });
 }
 /** The route's static render opens only when nothing else will open the Observer. */

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

@@ -35,6 +35,7 @@ export function previewRouteRun(args) {
             io: args.io,
             port: args.options.port ?? "0",
             ...(args.options.detach === undefined ? {} : { detach: args.options.detach }),
+            ...(args.options.serve === undefined ? {} : { serve: args.options.serve }),
             ...(openOverride === undefined ? {} : { open: openOverride }),
         })
         : undefined;

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

@@ -5,7 +5,8 @@ import { serveObserver } from "../../observer/render.js";
 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 { followDecision, 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";
@@ -24,7 +25,9 @@ export function sharedWorldRouteRun(args) {
         mode: args.mode,
         wantsMachine,
     });
-    const wantsFollow = args.mode === "watch" && !wantsMachine && args.options.detach !== true && dryRun !== true;
+    const wantsFollow = args.mode === "watch" &&
+        dryRun !== true &&
+        followDecision({ wantsMachine, detach: args.options.detach, serve: args.options.serve }).follow;
     const port = parseObserverPort(args.options.port ?? "0");
     const failConcurrent = (message, runId) => {
         const result = {
@@ -118,6 +121,7 @@ export function sharedWorldRouteRun(args) {
             }
             writeResult(args.command, args.io, output, formatConcurrentSharedWorldStudyHuman);
             args.io.setExitCode(result.ok && automaticAnalysisSucceeded(result) ? 0 : 2);
+            await writeRunFindings(args.command, args.io, args.options.cwd, result);
             if (server && output.observer?.ok) {
                 await followObserver(args.io, output.observer, server);
             }

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

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

package/dist/cli/commands/watch.js

@@ -5,7 +5,8 @@ import { runDryRun } from "../../run/dry-run.js";
 import { runStudyCommand } from "./study-run.js";
 import { addRunOptions, studyOnlyFlags } from "./run-command.js";
 import { applyEnvFileOption, collectRepeated, dotenvPathOf, formatRunHuman, parseObserverPort, parsePositiveInteger, wantsJson, writeResult, } from "../io.js";
-import { followObserver, formatObserverHuman, watchExposeRequested } from "../observer-follow.js";
+import { followDecision, followObserver, formatObserverHuman, unattendedObserverWarning, watchExposeRequested, } from "../observer-follow.js";
+import { cli } from "../invocation.js";
 export function registerWatchCommand(parent, io) {
     // A run's flags come from addRunOptions, the helper `run` uses, so the two cannot drift.
     addRunOptions(parent
@@ -23,6 +24,7 @@ export function registerWatchCommand(parent, io) {
         .option("--allow-email <addr>", "Edge OAuth allow rule: permit this email. Repeatable. Requires --oauth.", collectRepeated)
         .option("--allow-domain <domain>", "Edge OAuth allow rule: permit this domain. Repeatable. Requires --oauth.", collectRepeated)
         .option("--public-url <origin>", "Bring-your-own authed edge (Cloudflare Access/Tailscale/manual). Binds loopback and trusts your edge. Requires --expose.")
+        .addOption(new Option("--serve", "Serve the Observer and stay attached until Ctrl-C even without an interactive terminal; by default an agent's shell or a pipe gets the result and an exit.").conflicts(["detach", "json"]))
         // Hidden: watch rejects --safe with a pointer to the library filter and to edge auth, which
         // a bare "unknown option" would lose.
         .addOption(new Option("--safe").hideHelp())
@@ -37,7 +39,7 @@ export function registerWatchCommand(parent, io) {
         "Watch a live computer-use run from your phone through an authenticated tunnel:",
         "  humanish watch my-browser-study --expose --tunnel ngrok --oauth google --allow-email you@example.com",
         "",
-        "Agent/CI path:",
+        "Agent/CI path (without an interactive terminal, watch prints the result and exits):",
         "  humanish watch --json --no-open",
         "",
         "Saved runs:",
@@ -84,7 +86,7 @@ async function handleWatch(io, named, parsed, command) {
     if (watchExposeRequested(options)) {
         refuseWatch(command, io, options.cwd, {
             code: "HUMANISH_WATCH_OPTION_CONFLICT",
-            message: "--expose/--tunnel/--oauth apply only to a live computer-use run; to expose finished evidence use `humanish observe --all --expose`.",
+            message: `--expose/--tunnel/--oauth apply only to a live computer-use run; to expose finished evidence use \`${cli("observe --all --expose")}\`.`,
         });
         return;
     }
@@ -107,7 +109,12 @@ async function handleWatch(io, named, parsed, command) {
         : options.open === true
             ? true
             : !wantsMachine && process.stdout.isTTY === true;
-    const wantsFollow = !wantsMachine && options.detach !== true;
+    const decision = followDecision({
+        wantsMachine,
+        detach: options.detach,
+        serve: options.serve,
+    });
+    const wantsFollow = decision.follow;
     const staticOpen = wantsFollow ? false : shouldOpen;
     const rendered = await renderWatchEvidence(io, command, options, target.requestedParticipantCount, staticOpen);
     if (rendered === undefined)
@@ -116,6 +123,7 @@ async function handleWatch(io, named, parsed, command) {
         follow: wantsFollow,
         open: shouldOpen,
         port: target.port,
+        unattended: decision.unattended,
     });
 }
 function refuseWatch(command, io, cwd, refusal) {
@@ -174,6 +182,8 @@ async function renderWatchEvidence(io, command, options, requestedParticipantCou
 async function reportWatch(io, command, rendered, serve) {
     let server = null;
     let result = rendered;
+    if (rendered.ok && serve.unattended)
+        result = { ...rendered, warnings: [...rendered.warnings, unattendedObserverWarning("watch")] };
     if (rendered.ok && serve.follow) {
         server = await serveObserver(rendered, { open: serve.open, port: serve.port });
         result = {

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";