humanish 0.110.1 → 0.110.3

package/ARCHITECTURE.md

@@ -9,25 +9,20 @@ longer declares that name. [CONTEXT.md](CONTEXT.md) defines the domain terms, an
 
 The steps follow a live computer-use study on a hosted E2B desktop. Every route shares steps 1, 2, 7
 and 8. Steps 3 to 6 run in the route's admit function and the `run()` it returns, which `runStudyWith`
-reaches through `admitPlan` (`src/run-study.ts`):
+reaches through `admitPlan` (`src/run-study.ts`). Four of the admit functions hand their checks and
+the body they run inside the run scope to `admitRoute` (`src/run/route-shell.ts`). It completes the
+automatic analysis of a refusal, and its `run()` opens the run scope, runs the body and completes
+the analysis of the run:
 
-- computer-use: `admitComputerUsePlan` (`src/routes/computer-use/route.ts`); its `run()` calls
-  `runAdmittedCuaRun` (`src/routes/computer-use/route.ts`).
-- scripted: `admitScriptedPlan` (`src/routes/scripted/route.ts`); its `run()` calls
-  `runScriptedPlan` (`src/routes/scripted/route.ts`).
-- terminal: `admitTerminalPlan` (`src/routes/terminal/route.ts`); its `run()` calls
-  `runAdmittedTerminalRun` (`src/routes/terminal/route.ts`).
-- shared-world: `admitSharedWorldPlan` (`src/routes/shared-world/route.ts`); its `run()` calls
-  `runAdmittedSharedWorldRun` (`src/routes/shared-world/route.ts`).
+- computer-use: `admitComputerUsePlan` (`src/routes/computer-use/route.ts`), with the checks in
+  `admitCuaRun` (`src/routes/computer-use/setup.ts`).
+- scripted: `admitScriptedPlan` (`src/routes/scripted/route.ts`), whose checks run inside the run.
+- terminal: `admitTerminalPlan` (`src/routes/terminal/route.ts`), with a live plan's checks in
+  `checkLiveTerminalMachine` (`src/routes/terminal/session.ts`).
+- shared-world: `admitSharedWorldPlan` (`src/routes/shared-world/route.ts`).
 - preview: `admitPreviewPlan` (`src/routes/preview.ts`); its `run()` calls `runPreviewPlan`
   (`src/routes/preview.ts`), which publishes a fixture bundle.
 
-`runComputerUsePlan` (`src/routes/computer-use/route.ts`), `runTerminalPlan`
-(`src/routes/terminal/route.ts`) and `runSharedWorldPlan` (`src/routes/shared-world/route.ts`)
-admit and run in one call. Only tests call them, directly or through the route modules'
-`runCuaActorStudy`, `runTerminalProductStudy` and `runConcurrentSharedWorld`. `runStudyWith` and the CLI do
-not.
-
 1. **Parse.** `runStudyCommand` (`src/cli/commands/study-run.ts`) calls `resolveStudyManifest`
    (`src/study/discover.ts`), which calls `parseStudy` (`src/study/config.ts`). It rejects unknown
    keys and the compositions the
@@ -107,7 +102,7 @@ not.
 | `humanish/`                | This repo's own studies, personas, scenarios, fixtures and coverage notes                                                       | `humanish/studies/first-run.yaml`   |
 | `examples/`                | Library examples shipped in the npm package: a participant and a scorer                                                         | `examples/README.md`                |
 | `adapters/`                | Adapter fixture sets that `tests/study/adapter-fixtures.test.ts` checks                                                         | `adapters/fixtures/README.md`       |
-| `bench/`                   | Benchmark apps with planted defects and their dated results                                                                     | `bench/DEFECTS.md`                  |
+| `bench/`                   | Benchmark apps with planted defects, the scored runner behind `pnpm bench` and the September results                            | `bench/DEFECTS.md`                  |
 | `fixtures/`                | Synthetic apps and cases that tests and scripts copy                                                                            | `fixtures/minimal-app/README.md`    |
 | `skills/`                  | The companion agent skill that `npx skills add` installs                                                                        | `skills/humanish/SKILL.md`          |
 | `runtime/`                 | Desktop and browser image recipes                                                                                               | `runtime/browser-guest/README.md`   |

package/CHANGELOG.md

@@ -8,6 +8,32 @@ The Unreleased section holds the full notes for the next version until it is tag
 
 ## Unreleased
 
+## 0.110.3: Ctrl-C at the watch prompt, review says analysis is off, E2B docs links kept (2026-10-05)
+
+humanish 0.110.3 runs the `watch` and `observe` shutdown, and prints `watch stopped` or `observe
+stopped`, when a Ctrl-C lands right at their prompt. It starts no automatic analysis for a run a
+signal interrupted. `humanish review` says when a study's `review.analysis: false` is why a live
+run has no findings. `humanish verify` no longer blocks a run whose text holds a URL followed by an
+escaped line break and an `E2B_` variable, and redacted output keeps the E2B docs link that E2B's
+401 names. The `--env-file` alias is now removed in 0.112.0. Inside, the computer-use, scripted,
+terminal and shared-world routes run through one shell, `admitRoute` in `src/run/route-shell.ts`;
+the live smoke ran each route on it.
+
+[Release notes](https://github.com/danielgwilson/humanish/releases/tag/v0.110.3)
+
+## 0.110.2: Credential URLs refused, terminal key proxied, watch exits for agents (2026-10-05)
+
+humanish 0.110.2 refuses a study URL that carries a user name, password or credential parameter,
+and `humanish verify` catches all 41 secret formats its test lists, where 0.110.1 caught 13. A
+terminal study that declares no `execution.runtimeAuth` keeps the OpenAI key in E2B's host-side
+proxy rule (`openai-egress`) and gives Codex a placeholder. No Observer server hands out
+`sandbox-receipts.ndjson` or `status.json`, and a Ctrl-C during desktop startup no longer writes
+the raw sandbox id outside `sandbox-receipts.ndjson`. For a coding agent, `watch` and `observe`
+print the Observer path and exit when nobody is at a terminal, a rerun of `init` rewrites only its
+own `AGENTS.md` section, and suggested commands use one invocation style.
+
+[Release notes](https://github.com/danielgwilson/humanish/releases/tag/v0.110.2)
+
 ## 0.110.1: Claude participants restricted, sandboxes reclaimed by tag (2026-10-04)
 
 humanish 0.110.1 starts a Claude Code participant with Read as its only tool, in a scratch folder,

package/CONTEXT.md

@@ -28,7 +28,7 @@ bundle and output fields keep older spellings; the second table maps them.
 | computer use        | A model drives a participant by reading screenshots of a desktop and acting with mouse and keyboard. `openai-computer-use` and `local-agent` are the computer-use actors. CUA is the short form in code names such as `CuaExecutor` and in the older spellings listed under `cua` below.                                                                                                                                                                                                                                              | `src/routes/computer-use/`, `src/actors/computer-use/`                                                                                                                                                                                                                                                                                                                                                      |
 | fan-out             | A computer-use run with more than one participant, each on its own desktop, or any rerun. It writes the fan-out bundle shape and passes only when every expected participant passes. One participant without a rerun keeps the single-participant shape.                                                                                                                                                                                                                                                                              | `buildCuaFanoutBundle` in `src/routes/computer-use/fanout-bundle.ts`; `judgeComputerUseRun` in `src/routes/computer-use/bundle.ts`                                                                                                                                                                                                                                                                          |
 | route               | The execution path for a study: `computer-use`, `shared-world`, `scripted`, `terminal` or `preview`. `preview` writes a dry-run bundle for `this-repo` subjects with no live participant.                                                                                                                                                                                                                                                                                                                                             | `routeOf` and `StudyRoute` in `src/study/plan.ts`; predicates in `src/study/routing.ts`; one folder or file per route in `src/routes/`                                                                                                                                                                                                                                                                      |
-| plan                | What `planStudy` decides about a study before anything runs: the study id, whether it is a dry run, the analysis settings and the keys, connections and env vars the run needs, plus the route's participants, caps and own fields. There is one variant per route. `planStudy` returns a plan, or a refusal with the route's error code, and the route's run function (`runComputerUsePlan` and the others) takes the plan.                                                                                                          | `StudyPlan` in `src/study/plan-types.ts`; `planStudy` in `src/study/plan.ts`; each route's planner in its `plan.ts`                                                                                                                                                                                                                                                                                         |
+| plan                | What `planStudy` decides about a study before anything runs: the study id, whether it is a dry run, the analysis settings and the keys, connections and env vars the run needs, plus the route's participants, caps and own fields. There is one variant per route. `planStudy` returns a plan, or a refusal with the route's error code, and the route's admit function (`admitComputerUsePlan` and the others) takes the plan.                                                                                                      | `StudyPlan` in `src/study/plan-types.ts`; `planStudy` in `src/study/plan.ts`; each route's planner in its `plan.ts`                                                                                                                                                                                                                                                                                         |
 | substrate           | Where a participant's desktop or shell runs: a hosted E2B sandbox, or a local Firecracker VM (inside Lima on macOS).                                                                                                                                                                                                                                                                                                                                                                                                                  | `src/substrates/e2b/`, `src/substrates/local/`                                                                                                                                                                                                                                                                                                                                                              |
 | participant desktop | The desktop one computer-use or shared-world participant drives: a substrate plus the route's concerns, such as subject provisioning, comms and the participant's plan. It lives in the route, so `src/substrates/` holds only provider primitives ([ADR 0004](docs/decisions/0004-participant-desktops-stay-in-the-route.md)).                                                                                                                                                                                                       | `ParticipantDesktop` in `src/routes/computer-use/participant-desktop.ts`; `createE2BParticipantDesktop` in `src/routes/computer-use/e2b-desktop/desktop.ts`; the local VM's in `src/routes/computer-use/local-vm.ts`                                                                                                                                                                                        |
 | receipt             | A line in a run's `sandbox-receipts.ndjson` that records a sandbox's id, provider, the participant or subject it belongs to (`laneId`), and its time limit as soon as the sandbox is created, before any work runs in it. `humanish reclaim` kills sandboxes by these ids after an interrupted run.                                                                                                                                                                                                                                   | `SandboxReceipt` in `src/run/sandbox-receipts.ts`; `reclaimRunSandboxes` in `src/run/reclaim.ts`                                                                                                                                                                                                                                                                                                            |

package/README.md

@@ -38,7 +38,8 @@ npx humanish run first-run
 
 `init` writes starter studies and personas under `humanish/`, adds `.humanish/` to
 `.gitignore`, and adds `humanish:*` scripts to `package.json` and a humanish section to
-`AGENTS.md`. It never overwrites an existing study file. `run first-run` is a dry run: four
+`AGENTS.md`, and lists each file it created or changed. It never overwrites an existing study
+file; a rerun replaces only its own `AGENTS.md` section. `run first-run` is a dry run: four
 synthetic participants, with no browser, model, key or spend. It prints:
 
 ```text
@@ -357,12 +358,12 @@ never reads the subject app's own `.env` files.
 **What leaves your machine.** [Trust boundaries](https://humanish.dev/docs/trust-boundaries)
 has the providers' retention terms.
 
-| Party                | What it receives                                                                                                                                                                                                                                                                                                                                            | When                                                                                                                             |
-| -------------------- | ----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | -------------------------------------------------------------------------------------------------------------------------------- |
-| OpenAI               | Each step's screenshot, the persona, the mission and the actions so far; after a run, selected text and captures for analysis; for an external-public shared-world study, the host participant's screen while its lobby code is read; for a terminal study, the agent's requests from the E2B sandbox                                                       | `openai-computer-use` participants; automatic or `humanish analyze` runs; external-public shared-world studies; terminal studies |
-| Codex or Claude Code | The same screenshots and prompts, through your signed-in agent and its provider                                                                                                                                                                                                                                                                             | `local-agent` participants, local browser studies, the Codex analyst                                                             |
-| E2B                  | A desktop or shell running your app and everything on its screen; the repository a `clone` subject names; your working tree for a `local-tree` subject, minus gitignored files, `.env*` and other secret-shaped files; the credentials you declare for the subject app; for a terminal study, your OpenAI key unless `execution.runtimeAuth: openai-egress` | Every hosted study                                                                                                               |
-| PostHog              | Telemetry events, described [below](#check-what-telemetry-sends)                                                                                                                                                                                                                                                                                            | By default                                                                                                                       |
+| Party                | What it receives                                                                                                                                                                                                                                                                                                                                       | When                                                                                                                             |
+| -------------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------ | -------------------------------------------------------------------------------------------------------------------------------- |
+| OpenAI               | Each step's screenshot, the persona, the mission and the actions so far; after a run, selected text and captures for analysis; for an external-public shared-world study, the host participant's screen while its lobby code is read; for a terminal study, the agent's requests from the E2B sandbox                                                  | `openai-computer-use` participants; automatic or `humanish analyze` runs; external-public shared-world studies; terminal studies |
+| Codex or Claude Code | The same screenshots and prompts, through your signed-in agent and its provider                                                                                                                                                                                                                                                                        | `local-agent` participants, local browser studies, the Codex analyst                                                             |
+| E2B                  | A desktop or shell running your app and everything on its screen; the repository a `clone` subject names; your working tree for a `local-tree` subject, minus gitignored files, `.env*` and other secret-shaped files; the credentials you declare for the subject app; for a terminal study with `execution.runtimeAuth: openai-env`, your OpenAI key | Every hosted study                                                                                                               |
+| PostHog              | Telemetry events, described [below](#check-what-telemetry-sends)                                                                                                                                                                                                                                                                                       | By default                                                                                                                       |
 
 ## Find the main commands
 

package/dist/actors/computer-use/actor.js

@@ -63,7 +63,7 @@ export async function runCuaActorSession(options) {
 }
 function defaultProvider(openai, strictSpend = false) {
     if (!openai) {
-        throw new Error("runCuaActorSession requires either `provider` (injected) or `openai` provider options.");
+        throw new Error("A computer-use session requires either `provider` (injected) or `openai` provider options.");
     }
     return createOpenAiResponsesProvider({
         ...openai,
@@ -72,7 +72,7 @@ function defaultProvider(openai, strictSpend = false) {
 }
 function defaultExecutor(desktop, executorOptions) {
     if (!desktop) {
-        throw new Error("runCuaActorSession requires either `executor` (injected) or `desktop` to build one.");
+        throw new Error("A computer-use session requires either `executor` (injected) or `desktop` to build one.");
     }
     return createE2BDesktopExecutor(desktop, executorOptions ?? {});
 }

package/dist/actors/computer-use/loop/ending.js

@@ -96,7 +96,7 @@ export function spendLimit(session, estimate, maxUsd) {
 // trip.
 export const nonFiniteEstimate = {
     completionReason: "harness_error",
-    reason: "the injected estimateTurnCostUsd returned a non-finite estimate while caps.maxUsd is set; the estimator receives one ActorTokenUsage object. Failing closed instead of running uncapped.",
+    reason: "the injected estimateTurnCostUsd returned a non-finite estimate while caps.maxUsd is set; the estimator receives one object with the running token totals. Failing closed instead of running uncapped.",
 };
 /** A study-level stop is a recruiting decision hitting its limit, not this participant's runaway. */
 export function runSpendLimit(reason) {

package/dist/actors/local-agent/cli.d.ts

@@ -123,6 +123,12 @@ export declare function detectLocalAgents(options?: DetectLocalAgentsOptions): P
 export declare const NO_LOCAL_AGENT_MESSAGE = "no local coding agent found. openai-computer-use needs OPENAI_API_KEY; local-agent needs Codex or Claude Code installed and signed in. Hosted desktops also need E2B_API_KEY.";
 /** Whether a signed-in agent can still not run participants here: an old Claude Code. */
 export declare function localAgentVersionRefusal(agent: DetectedLocalAgent): string | undefined;
+/**
+ * Whether an installed agent can run participants here: it reports signed in under the
+ * participant's environment, and a Claude Code is at or above the floor. Doctor's rows decide their
+ * status from this, so a row whose message says the agent cannot run participants is never "ok".
+ */
+export declare function localAgentReady(agent: DetectedLocalAgent): boolean;
 /** Doctor's row for one installed agent, in the register the other rows use. */
 export declare function localAgentDoctorMessage(agent: DetectedLocalAgent): string;
 export {};

package/dist/actors/local-agent/cli.js

@@ -474,6 +474,14 @@ export function localAgentVersionRefusal(agent) {
         ? claudeCodeVersionMessage(agent.version)
         : undefined;
 }
+/**
+ * Whether an installed agent can run participants here: it reports signed in under the
+ * participant's environment, and a Claude Code is at or above the floor. Doctor's rows decide their
+ * status from this, so a row whose message says the agent cannot run participants is never "ok".
+ */
+export function localAgentReady(agent) {
+    return agent.authStatus === "authenticated" && localAgentVersionRefusal(agent) === undefined;
+}
 /** Doctor's row for one installed agent, in the register the other rows use. */
 export function localAgentDoctorMessage(agent) {
     const outdated = localAgentVersionRefusal(agent);

package/dist/actors/local-agent/readiness.js

@@ -5,6 +5,7 @@
 // error code.
 import { describeCodexCliAdmission } from "../codex/codex-admission.js";
 import { checkHostedCodexCompatibility, detectLocalAgents, localAgentVersionRefusal, } from "./cli.js";
+import { cli } from "../../cli/invocation.js";
 export async function localAgentRefusal(args) {
     const { agent, env, caps } = args;
     const available = await detectLocalAgents({ env, only: agent });
@@ -38,7 +39,7 @@ export async function localAgentRefusal(args) {
             kind: "unsupported",
             message: compatibility === "unsupported_platform"
                 ? `Hosted Codex participants require Linux or macOS on x64 or arm64. This host is ${process.platform}/${process.arch}; no desktop was launched.`
-                : `Hosted Codex participants need a Codex CLI release humanish runs: ${describeCodexCliAdmission()}. Run \`humanish doctor\` for the release it found and the command that replaces it; no desktop was launched.`,
+                : `Hosted Codex participants need a Codex CLI release humanish runs: ${describeCodexCliAdmission()}. Run \`${cli("doctor")}\` for the release it found and the command that replaces it; no desktop was launched.`,
         };
     }
     if (chosen.billing === "account-unknown" &&

package/dist/actors/registry.js

@@ -74,7 +74,7 @@ export const actorRegistry = {
     },
     // The ActorId names the terminal-product dispatch slot; the live route records the concrete
     // provider as "codex". keyPlacement "in-sandbox-command-scoped" is registry-declared and
-    // enforced by runTerminalProductStudy before it creates a sandbox, which is where this actor runs.
+    // enforced by the terminal route before it creates a sandbox, which is where this actor runs.
     "codex-exec": {
         id: "codex-exec",
         label: "Codex Exec (autonomous terminal agent, in-sandbox)",

package/dist/analysis/automatic-completion.js

@@ -25,6 +25,14 @@ export async function completeAutomaticAnalysis(result, finished, config, input,
             automaticAnalysis: { state: "skipped", reason: "AUTOMATIC_ANALYSIS_SOURCE_UNAVAILABLE" },
         };
     }
+    // A signal is stopping this process: the run is recorded interrupted, and the process exits
+    // once its sandboxes are reclaimed, so no analysis starts.
+    if (finished.interrupted)
+        return {
+            ...result,
+            ...origin,
+            automaticAnalysis: { state: "skipped", reason: "AUTOMATIC_ANALYSIS_ACTOR_CANCELLED" },
+        };
     const prepared = finished.paths;
     const seams = input?.deps?.analysis;
     const signal = input?.analysisSignal;

package/dist/cli/commands/observe.js

@@ -4,7 +4,7 @@ import { SERVE_SCHEMA, serveObserverLibrary } from "../../observer/serve.js";
 import { startExposedObserver, validateExposure } from "../../observer/exposure.js";
 import { ServeTunnelError } from "../../observer/tunnel.js";
 import { collectRepeated, CWD_OPTION_DESCRIPTION, formatRunHuman, freePortOption, JSON_OPTION_DESCRIPTION, parseObserverPort, RUN_OPTION_DESCRIPTION, wantsJson, writeResult, } from "../io.js";
-import { exitCodeForSignal, formatObserverHuman, } from "../observer-follow.js";
+import { exitCodeForSignal, formatObserverHuman, personAtTerminal, unattendedObserverWarning, } from "../observer-follow.js";
 export function registerObserveCommand(parent, io) {
     addLibraryOptions(parent
         .command("observe")
@@ -16,6 +16,7 @@ export function registerObserveCommand(parent, io) {
         .option("--cwd <path>", CWD_OPTION_DESCRIPTION, ".")
         .option("--open", "Open the Observer in the default browser.")
         .option("--no-open", "Serve without opening a browser.")
+        .option("--serve", "Serve one run until Ctrl-C even without an interactive terminal; by default an agent's shell or a pipe gets the Observer path and an exit.")
         .option("--json", JSON_OPTION_DESCRIPTION))
         .addHelpText("after", [
         "",
@@ -32,6 +33,8 @@ export function registerObserveCommand(parent, io) {
         "The server binds 127.0.0.1 only. One run exposes just that run's bundle directory; --all",
         "serves the run library. It stays attached until Ctrl-C; file:// security policy and live",
         "refresh are why loopback http is preferred over opening the index.html path directly.",
+        "Without an interactive terminal, as in an agent's shell or a pipe, observe for one run",
+        "prints the Observer path and exits; --serve keeps it serving.",
         "",
         "--safe, --expose, --tunnel, --tunnel-domain, --oauth, --allow-email, --allow-domain and",
         "--public-url need --all. Exposure only ever happens through an authenticated edge (ngrok",
@@ -119,9 +122,19 @@ async function observeRun(io, options, command) {
         io.setExitCode(2);
         return;
     }
+    const wantsMachine = wantsJson(command);
+    if (options.serve !== true && !personAtTerminal()) {
+        // Nobody can press Ctrl-C here, so a server would wait forever: print the path and exit.
+        const result = {
+            ...rendered,
+            warnings: [...rendered.warnings, unattendedObserverWarning("observe")],
+        };
+        writeResult(command, io, result, formatObserverHuman);
+        io.setExitCode(0);
+        return;
+    }
     // Reuse the contained current-data projection, scoped to this run. A raw static
     // server would miss runtime status and could replay stored iframe grants.
-    const wantsMachine = wantsJson(command);
     const shouldOpen = options.open === false
         ? false
         : options.open === true
@@ -151,8 +164,6 @@ async function serveObserveUntilSignal(io, server, options) {
     // Keep the JSON envelope on stdout clean: route attach/stop chatter to stderr
     // for machine output, and to stdout for humans.
     const note = options.json ? io.writeErr : io.writeOut;
-    note(`serving: ${server.url}\n`);
-    note("serving: press Ctrl-C to stop\n");
     await new Promise((resolveWait) => {
         const signals = ["SIGINT", "SIGTERM", "SIGHUP"];
         const handlers = new Map();
@@ -182,6 +193,9 @@ async function serveObserveUntilSignal(io, server, options) {
             handlers.set(signal, handler);
             process.once(signal, handler);
         }
+        // The prompt follows the handlers, as in followObserver.
+        note(`serving: ${server.url}\n`);
+        note("serving: press Ctrl-C to stop\n");
     });
 }
 async function handleServe(io, options, command) {

package/dist/cli/commands/run-signals.js

@@ -2,7 +2,8 @@
 // hangup signal prints one line saying humanish is stopping, refuses any further sandbox create,
 // marks each unfinished run in this process interrupted, reclaims its sandboxes (by receipt, by
 // the ids its in-flight creates report, and by its E2B tags), runs the registered shutdown
-// cleanups (watch's Observer server and tunnel) and exits 128+n, all within one deadline. A
+// cleanups (watch's Observer server and tunnel), sweeps the interrupted runs' files of their raw
+// sandbox ids as Run.finish does for a finished run, and exits 128+n, all within one deadline. A
 // second signal prints the reclaim command for each run not yet reclaimed and exits at once.
 // Routes take no abort signal, so the bundle is not finished, but the record ends at once and no
 // sandbox the run created waits for its timeout. Analysis has its own cancel handlers
@@ -12,10 +13,12 @@ import { activeRuns } from "../../run/active-runs.js";
 import { LATEST_RUN_ALIAS } from "../../run/locate.js";
 import { reclaimPinnedRunSandboxes, } from "../../run/reclaim.js";
 import { stopSandboxCreates } from "../../run/sandbox-creates.js";
+import { scrubRunSandboxIds } from "../../run/sandbox-ids.js";
 import { SANDBOX_RECEIPTS_ARTIFACT } from "../../run/sandbox-receipts.js";
 import { plural } from "../../run/text.js";
 import { shellArg } from "../../substrates/shell.js";
 import { exitCodeForSignal } from "../observer-follow.js";
+import { cli } from "../invocation.js";
 /** How long the handler waits for interrupt, reclaim and cleanups before it exits anyway. */
 const INTERRUPT_RECLAIM_DEADLINE_MS = 10_000;
 /** Each kill's own request timeout, inside the deadline. Kills run concurrently. */
@@ -125,7 +128,13 @@ async function stopActiveRuns(io, signal, stopping, options) {
             stop.report = reclaimSummary(stop.run, reclaimed);
         }),
         ...[...shutdownCleanups].map((cleanup) => cleanup().catch(() => undefined)),
-    ]);
+    ]).then(() => 
+    // Last, so it also covers what the route recorded while reclaim ran, such as a desktop
+    // startup error that quotes the sandbox the kill cut short. A run stopped by the deadline is
+    // not swept; verify grades a file that names a receipt's id local_only.
+    Promise.all(stopping
+        .filter((stop) => stop.report !== null)
+        .map((stop) => scrubRunSandboxIds(stop.run.paths).catch(() => undefined))));
     const finished = await withDeadline(work, deadlineMs, options.deadline);
     for (const stop of stopping) {
         if (stop.report === null)
@@ -159,9 +168,9 @@ function withDeadline(work, ms, wait) {
  */
 function recovery(run) {
     if (run.runId === LATEST_RUN_ALIAS)
-        return `its id is \`${LATEST_RUN_ALIAS}\`, which \`humanish reclaim --run\` reads as the newest run, so kill the ids in ${path.join(run.paths.relativeRunRoot, SANDBOX_RECEIPTS_ARTIFACT)} by hand`;
+        return `its id is \`${LATEST_RUN_ALIAS}\`, which \`${cli("reclaim --run")}\` reads as the newest run, so kill the ids in ${path.join(run.paths.relativeRunRoot, SANDBOX_RECEIPTS_ARTIFACT)} by hand`;
     const cwd = path.resolve(run.cwd) === process.cwd() ? "" : ` --cwd ${shellArg(run.cwd)}`;
-    return `run \`humanish reclaim --run ${shellArg(run.runId)}${cwd}\``;
+    return `run \`${cli(`reclaim --run ${shellArg(run.runId)}${cwd}`)}\``;
 }
 function reclaimSummary(run, reclaimed) {
     if (reclaimed === undefined)

package/dist/cli/commands/runs.js

@@ -11,6 +11,7 @@ import { applyEnvFileOption, CWD_OPTION_DESCRIPTION, DOTENV_OPTION_DESCRIPTION,
 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")
@@ -162,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,
@@ -208,7 +209,7 @@ async function runReclaimCommand(io, command, options) {
 /** The command that finishes what a reclaim left open, with --cwd when it was given. */
 function reclaimCommand(result, cwd, preflight) {
     const target = preflight ? "--preflight" : `--run ${shellArg(result.runId)}`;
-    return `humanish reclaim ${target}${cwd === "." ? "" : ` --cwd ${shellArg(cwd)}`}`;
+    return cli(`reclaim ${target}${cwd === "." ? "" : ` --cwd ${shellArg(cwd)}`}`);
 }
 function formatReclaimHuman(result, cwd, preflight) {
     const lines = [];
@@ -216,7 +217,9 @@ function formatReclaimHuman(result, cwd, preflight) {
     const search = result.tagSearch.status === "done"
         ? `E2B lists ${plural(result.tagSearch.found, "more sandbox", "more sandboxes")} tagged with it`
         : `E2B tag search ${result.tagSearch.status}`;
-    lines.push(`${check ? "Reclaim check" : "Reclaim"} ${result.runId}: ${result.state}. ${plural(result.receiptCount, "sandbox receipt")}; ${search}.`);
+    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}, from ${outcome.source}): ${outcome.state}${outcome.detail ? `: ${outcome.detail}` : ""}`);
     }
@@ -229,17 +232,41 @@ function formatReclaimHuman(result, cwd, preflight) {
     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",
 };
+/** 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: its verdict, summary and gaps, its analysis findings, and where review.json is.
- * A pass verdict on a run whose own ok is false leads with how the run ended (runDisplay), then why.
+ * 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)) {
@@ -252,18 +279,14 @@ 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 verdict = REVIEW_VERDICTS[result.verdict];
     const display = result.display;
-    const headline = result.verdict === "pass" && display !== undefined && display.state !== "passed"
-        ? `${display.label} (verdict pass)`
-        : verdict;
     return ([
-        `humanish review ${result.runId}: ${headline}`,
+        `humanish review ${result.runId}: ${reviewHeadline(result.verdict, display)}`,
         ...(display?.reason === undefined ? [] : [`why: ${display.reason}`]),
         "",
         result.summary,
@@ -311,7 +334,7 @@ function formatVerifyHuman(result) {
     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) {

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,7 @@ 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";
@@ -87,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;
@@ -100,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) {
@@ -117,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)

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-shared-world.js

@@ -5,7 +5,7 @@ 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";
@@ -25,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 = {