humanish 0.110.1 → 0.110.2

package/ARCHITECTURE.md

@@ -107,7 +107,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,19 @@ The Unreleased section holds the full notes for the next version until it is tag
 
 ## Unreleased
 
+## 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/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/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/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

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 = {

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

@@ -5,11 +5,12 @@ import path from "node:path";
 import { probeKeySources, } from "../keys/key-resolution.js";
 import { desktopPeerAdvice, humanishInstall, } from "../substrates/e2b/peer-install.js";
 import { nodeSupportsTui, terminalSurfaceMessage, TUI_BUNDLE_URL } from "../tui/contract.js";
-import { detectLocalAgents, localAgentDoctorMessage, NO_LOCAL_AGENT_MESSAGE, } from "../actors/local-agent/cli.js";
+import { detectLocalAgents, localAgentDoctorMessage, localAgentReady, NO_LOCAL_AGENT_MESSAGE, } from "../actors/local-agent/cli.js";
 import { leftoverClaudeTranscripts } from "../actors/local-agent/claude-participant.js";
 import { studySetupChecks, studiesByRequiredKey, } from "../study/doctor.js";
 import { prepareSelectedOutputDirectory, } from "../run/contained-output.js";
 import { implicitProjectDirectoryExists, readImplicitProjectFile, validateCwd, } from "../run/project.js";
+import { cli } from "./invocation.js";
 const DOCTOR_SCHEMA = "humanish.doctor-result.v1";
 /**
  * Version 2.3.1 stopped holding a launched background command's event stream open. Version 2.3.2
@@ -100,7 +101,7 @@ export async function doctor(cwdInput, options = {}) {
             {
                 name: "setup route",
                 ok: true,
-                message: "General capabilities only. Use humanish doctor --study <study> for the selected participant's requirements and separate analysis readiness.",
+                message: `General capabilities only. Use ${cli("doctor --study <study>")} for the selected participant's requirements and separate analysis readiness.`,
             },
         ]),
     ];
@@ -173,7 +174,7 @@ async function sourceCheck(projectRoot) {
         ok,
         message: ok
             ? "committed humanish/ source directory is present and safe to read"
-            : "no readable humanish/ source directory; run humanish init --yes",
+            : `no readable humanish/ source directory; run ${cli("init --yes")}`,
     };
 }
 async function runtimeIgnoreCheck(projectRoot) {
@@ -183,7 +184,7 @@ async function runtimeIgnoreCheck(projectRoot) {
         ok,
         message: ok
             ? ".gitignore lists .humanish/"
-            : ".gitignore does not list .humanish/; run humanish init --yes",
+            : `.gitignore does not list .humanish/; run ${cli("init --yes")}`,
     };
 }
 /**
@@ -271,7 +272,9 @@ async function probeDoctorKeys(cwd, env, study, keyDeps, dotenv) {
  * The operator's own coding agents, one row each, reported as a capability and never a gate: a
  * machine with none is not broken, it just needs a provider key. These rows exist because "go make
  * an API key" is where most people trying humanish stop, and a developer very often already has one
- * of these signed in. An agent that is installed but not signed in is a note.
+ * of these signed in. An agent that cannot run participants (not signed in under the participant's
+ * environment, sign-in unknown, or a Claude Code below the floor) is a note; `--study` fails on it
+ * when the study selects that agent.
  */
 function localAgentChecks(agents) {
     if (agents.length === 0)
@@ -279,7 +282,7 @@ function localAgentChecks(agents) {
     return agents.map((agent) => ({
         name: `local agent ${agent.bin}`,
         ok: true,
-        ...(agent.authStatus === "authenticated" ? {} : { status: "note" }),
+        ...(localAgentReady(agent) ? {} : { status: "note" }),
         message: localAgentDoctorMessage(agent),
     }));
 }