humanish 0.110.2 → 0.110.4

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

package/CHANGELOG.md

@@ -8,6 +8,33 @@ The Unreleased section holds the full notes for the next version until it is tag
 
 ## Unreleased
 
+## 0.110.4: Scripted runs reclaim clean, review says interrupted, Chrome under a long TMPDIR (2026-10-05)
+
+humanish 0.110.4 fixes four findings of the 0.110.3 live smoke. `humanish reclaim --check` reports
+a live scripted run against an `app-url` subject `clean`, with reason `no-sandbox`, and exits 0.
+`humanish review` on a computer-use run stopped by Ctrl-C after its desktop started says the run
+was interrupted. A run that failed before any participant started no longer prints "Participants
+finished; preparing analysis…". The scripted route launches Chrome when `TMPDIR` is too long for
+Chrome's socket path. Planner refusals for a library config built without `parseStudy` name v3
+keys, and so does `humanish migrate` when one of those checks refuses a v2 file. Inside, a v3
+parser runs beside `parseStudy`, src reads the study through accessors, and `humanish migrate`
+reads v2 files through its own front end; the library API is unchanged.
+
+[Release notes](https://github.com/danielgwilson/humanish/releases/tag/v0.110.4)
+
+## 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,

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/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/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/actors/scripted-browser/actor.js

@@ -23,17 +23,26 @@ import { assertPreparedSelectedOutputDirectory, assertSafeOutputPathSegment, pre
 import { ACTOR_TRACE_SCHEMA, SCRIPTED_BROWSER_CAPABILITIES, } from "../contract.js";
 import { buildBlockedBrowserPersonaSteps, buildBrowserTrace, captureBlockedStepScreenshot, compactBrowserError, executeBrowserPersonaStep, probeAppUrl, sanitizeBrowserEvidenceUrl, screenshotPathForBrowserStep, surfaceScreenshotPath, tracePathForBrowserSurface, } from "./steps.js";
 import { LOOPBACK_EVIDENCE_URL_POLICY, } from "./types.js";
+import { chromeLaunchEnv, chromeLaunchError } from "./launch-env.js";
 /** Production default: lazy playwright-core import + chromium.launch, exactly as the driver
- *  always did. Kept in one place so the optional peer is touched by exactly one code path. */
+ *  always did. Kept in one place so the optional peer is touched by exactly one code path. A
+ *  `TMPDIR` too long for Chrome's singleton socket is replaced for Chrome (chromeLaunchEnv). */
 async function launchPlaywrightChromium(args) {
     const { chromium } = await import("playwright-core");
-    const browser = await chromium.launch({
-        executablePath: args.browserCommand,
-        headless: true,
-        args: [...CHROMIUM_EVIDENCE_HYGIENE_FLAGS, "--disable-gpu", "--disable-dev-shm-usage"],
-        timeout: args.timeoutMs,
-    });
-    return browser;
+    const env = await chromeLaunchEnv();
+    try {
+        const browser = await chromium.launch({
+            executablePath: args.browserCommand,
+            headless: true,
+            args: [...CHROMIUM_EVIDENCE_HYGIENE_FLAGS, "--disable-gpu", "--disable-dev-shm-usage"],
+            timeout: args.timeoutMs,
+            ...(env === undefined ? {} : { env }),
+        });
+        return browser;
+    }
+    catch (error) {
+        throw chromeLaunchError(error, env);
+    }
 }
 function assertScriptedSessionPathIds(options) {
     assertSafeOutputPathSegment(options.surface.id, "Browser surface id");

package/dist/actors/scripted-browser/launch-env.d.ts

@@ -0,0 +1,12 @@
+/**
+ * The environment to launch Chrome with: `env` with `TMPDIR` set to /tmp when its own `TMPDIR` is
+ * too long for the singleton socket and /tmp is a writable directory. Undefined when Chrome can
+ * launch with `env` as it is, or when /tmp cannot be used; chromeLaunchError then names the cause.
+ */
+export declare function chromeLaunchEnv(env?: NodeJS.ProcessEnv): Promise<NodeJS.ProcessEnv | undefined>;
+/**
+ * The launch error to report: one that names the cause and the fix when Chrome aborted because its
+ * singleton socket path was too long, and `error` itself otherwise. `env` is the environment
+ * Chrome was launched with.
+ */
+export declare function chromeLaunchError(error: unknown, env?: NodeJS.ProcessEnv): unknown;

package/dist/actors/scripted-browser/launch-env.js

@@ -0,0 +1,50 @@
+// Chrome's process singleton listens on a Unix socket at `$TMPDIR/<product>.XXXXXX/SingletonSocket`,
+// where the product is com.google.Chrome, or org.chromium.Chromium for Chromium and Chrome for
+// Testing. A Unix socket path holds at most 107 bytes on Linux and 103 on macOS, so under a longer
+// `TMPDIR`, such as a sandboxed agent's private temp directory, Chrome aborts at launch with
+// "Socket path too long", and Playwright reports only that the browser closed. The scripted
+// browser gives Chrome /tmp in that case; the browser profile stays where Playwright puts it.
+import { constants } from "node:fs";
+import { access } from "node:fs/promises";
+/** `/org.chromium.Chromium.XXXXXX/SingletonSocket`: the longest path Chrome adds to `TMPDIR`. */
+const SOCKET_SUFFIX_BYTES = 45;
+/** The longest socket path, without its NUL: `sun_path` holds 104 bytes on macOS, 108 elsewhere. */
+const SOCKET_PATH_MAX_BYTES = process.platform === "darwin" ? 103 : 107;
+/** Where Chrome makes its socket directory when `TMPDIR` is unset. */
+const DEFAULT_TMPDIR = "/tmp";
+/** The byte length of `TMPDIR` when Chrome's singleton socket path under it would be too long. */
+function overlongTmpdirBytes(env) {
+    const tmpdir = env.TMPDIR?.replace(/\/+$/, "");
+    if (tmpdir === undefined || tmpdir === "")
+        return undefined;
+    const bytes = Buffer.byteLength(tmpdir);
+    return bytes + SOCKET_SUFFIX_BYTES > SOCKET_PATH_MAX_BYTES ? bytes : undefined;
+}
+/**
+ * The environment to launch Chrome with: `env` with `TMPDIR` set to /tmp when its own `TMPDIR` is
+ * too long for the singleton socket and /tmp is a writable directory. Undefined when Chrome can
+ * launch with `env` as it is, or when /tmp cannot be used; chromeLaunchError then names the cause.
+ */
+export async function chromeLaunchEnv(env = process.env) {
+    if (process.platform === "win32" || overlongTmpdirBytes(env) === undefined)
+        return undefined;
+    try {
+        await access(DEFAULT_TMPDIR, constants.W_OK | constants.X_OK);
+    }
+    catch {
+        return undefined;
+    }
+    return { ...env, TMPDIR: DEFAULT_TMPDIR };
+}
+/**
+ * The launch error to report: one that names the cause and the fix when Chrome aborted because its
+ * singleton socket path was too long, and `error` itself otherwise. `env` is the environment
+ * Chrome was launched with.
+ */
+export function chromeLaunchError(error, env = process.env) {
+    const message = error instanceof Error ? error.message : String(error);
+    if (!message.includes("Socket path too long"))
+        return error;
+    const bytes = overlongTmpdirBytes(env);
+    return new Error(`Chrome could not start: its singleton socket path under \`TMPDIR\`${bytes === undefined ? "" : ` (${bytes} bytes)`} is longer than the ${SOCKET_PATH_MAX_BYTES} bytes a Unix socket path allows. Set \`TMPDIR\` to a directory of at most ${SOCKET_PATH_MAX_BYTES - SOCKET_SUFFIX_BYTES} bytes, such as /tmp, and run again.`);
+}

package/dist/analysis/automatic-completion.d.ts

@@ -9,7 +9,8 @@ export interface AnalysisInput {
     readonly deps?: Pick<StudyDeps, "analysis">;
     /** Cancels the analysis only. */
     readonly analysisSignal?: AbortSignal;
-    /** Receives analysis-started and analysis-finished. */
+    /** Receives analysis-started and analysis-finished, around the analysis of a run where a
+     *  participant's session started. */
     readonly emit?: (event: StudyEvent) => void;
 }
 export interface AutomaticAnalysisResult {

package/dist/analysis/automatic-completion.js

@@ -25,13 +25,26 @@ 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;
     let started = false;
     try {
-        input?.emit?.({ type: "analysis-started" });
-        started = true;
+        // The CLI prints "Participants finished" on analysis-started. A run where no participant's
+        // session started (it failed before, such as at E2B login) still records its analysis
+        // outcome, but without the two events.
+        if (finished.participantsRan) {
+            input?.emit?.({ type: "analysis-started" });
+            started = true;
+        }
         try {
             await validatePreparedRunRootIdentity(prepared);
         }

package/dist/cli/commands/migrate.js

@@ -1,4 +1,4 @@
-import { migrateStudies } from "../../study/migrate.js";
+import { migrateStudies, } from "../../study/migrate/migrate.js";
 import { CWD_OPTION_DESCRIPTION, JSON_OPTION_DESCRIPTION, wantsJson, writeResult, } from "../io.js";
 function formatValue(value) {
     const text = JSON.stringify(value);

package/dist/cli/commands/observe.js

@@ -164,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();
@@ -195,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/runs.js

@@ -217,9 +217,12 @@ 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}`;
+    const head = `${check ? "Reclaim check" : "Reclaim"} ${result.runId}: ${result.state}.`;
     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}.`);
+        ? `${head} It was a dry run, which creates no sandboxes, so E2B was not contacted.`
+        : result.reason === "no-sandbox"
+            ? `${head} Its status.json records that its route created no sandbox, so E2B was not contacted.`
+            : `${head} ${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}` : ""}`);
     }

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

@@ -13,6 +13,7 @@ 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";
+import { actorOf, declaredParticipantCount } from "../../study/study-fields.js";
 /**
  * The computer-use route's CLI setup: its settings, the watch and exposure plan, the runStudyWith options
  * with the live Observer hook, and how it presents the outcome or a run error. Undefined when
@@ -54,7 +55,7 @@ function refuseCua(args, dryRun, code, message) {
         ...studyResultIdentity("computer-use", args.config.id),
         ok: false,
         cwd: args.options.cwd,
-        actor: args.config.actors[0]?.type ?? "",
+        actor: actorOf(args.config)?.type ?? "",
         appUrl: "",
         dryRun,
         runId: args.options.runId ?? "not-created",
@@ -79,7 +80,7 @@ function resolveCuaSettings(args) {
         args.io.setExitCode(2);
         return undefined;
     }
-    const count = parseStudyCount(args.options.count, args.config.actors[0]?.count ?? 1);
+    const count = parseStudyCount(args.options.count, declaredParticipantCount(args.config) ?? 1);
     if (count === null) {
         args.io.writeErr("error: --count must be a positive integer.\n");
         args.io.setExitCode(2);

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

@@ -2,12 +2,13 @@ import { Command } from "commander";
 import { studyResultIdentity } from "../../run/study-result.js";
 import { formatRunHuman, parseStudyCount, writeResult, } from "../io.js";
 import { planObserver, showObserver, staticObserverOpen } from "../observer-follow.js";
+import { declaredParticipantCount } from "../../study/study-fields.js";
 /**
  * The preview route's CLI setup: the participant count and Observer plan, its runStudyWith options, and how it
  * presents the outcome. Undefined when setup has already written its own result.
  */
 export function previewRouteRun(args) {
-    const participantCount = parseStudyCount(args.options.count, args.config.actors[0]?.count ?? 4);
+    const participantCount = parseStudyCount(args.options.count, declaredParticipantCount(args.config) ?? 4);
     if (participantCount === null) {
         const result = {
             ...studyResultIdentity("preview", args.config.id),

package/dist/cli/commands/study-route-shared-world.js

@@ -9,8 +9,8 @@ import { followDecision, followObserver, showObserver, staticObserverOpen, withO
 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";
 import { studyResultIdentity } from "../../run/study-result.js";
+import { actorOf, participantList } from "../../study/study-fields.js";
 /**
  * The shared-world route's CLI setup: dry run, open and follow semantics, the live Observer server
  * the run attaches, and how it presents the outcome. Undefined when setup has already written its
@@ -34,10 +34,10 @@ export function sharedWorldRouteRun(args) {
             ...studyResultIdentity("shared-world", args.config.id),
             ok: false,
             cwd: args.options.cwd,
-            actor: args.config.actors[0]?.type ?? "",
+            actor: actorOf(args.config)?.type ?? "",
             topology: "shared-world",
             topologyMode: "concurrent",
-            roleCount: rosterOf(args.config.actors[0])?.length ?? 0,
+            roleCount: participantList(args.config)?.length ?? 0,
             concurrency: args.config.execution?.concurrency ?? 1,
             dryRun,
             runId: runId ?? args.options.runId ?? "not-created",

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

@@ -94,7 +94,7 @@ export async function runStudyCommand(args) {
     // checks (keys, runtime auth, subject env, the local agent, caps) refuse this machine, all before
     // the scorer loads, so none imports the scorer's host code. The scripted route's checks and the
     // run-id claim still come after it; the scripted route takes no scorer.
-    const routeRun = routeRunFor(route, { ...args, config });
+    const routeRun = ROUTE_RUNS[route]({ ...args, config });
     if (routeRun === undefined)
         return;
     // Every route's runStudyWith options carry the study's provenance, from here only.
@@ -155,24 +155,14 @@ function announcedKeyNames(config, options) {
     const planned = planStudy(config, { cwd: options.cwd, dryRun: false });
     return planned.ok ? keyNamesOf(planned.planned.plan) : undefined;
 }
-/** The route's CLI setup. Undefined when the setup has already written its own result. */
-function routeRunFor(route, args) {
-    switch (route) {
-        case "preview":
-            return previewRouteRun(args);
-        case "computer-use":
-            return computerUseRouteRun(args);
-        case "scripted":
-            return scriptedRouteRun(args);
-        case "terminal":
-            return terminalRouteRun(args);
-        case "shared-world":
-            return sharedWorldRouteRun(args);
-        default:
-            // Compile-time exhaustiveness: a future route must be handled here, not silently no-op.
-            throw new Error(`Unhandled study route: ${String(route)}`);
-    }
-}
+/** Each route's CLI setup. It returns undefined when it has already written its own result. */
+const ROUTE_RUNS = {
+    preview: previewRouteRun,
+    "computer-use": computerUseRouteRun,
+    scripted: scriptedRouteRun,
+    terminal: terminalRouteRun,
+    "shared-world": sharedWorldRouteRun,
+};
 function studyRerunFlagsRequested(options) {
     return options.rerunFailedFrom !== undefined || options.participants !== undefined;
 }

package/dist/cli/commands/study.js

@@ -4,6 +4,7 @@ import { Command, Option } from "commander";
 import { inspectStudyManifest, listStudyManifests } from "../../study/discover.js";
 import { runStudyPreflight, } from "../../study/preflight.js";
 import { applyEnvFileOption, CWD_OPTION_DESCRIPTION, DOTENV_OPTION_DESCRIPTION, dotenvPathOf, envFileAliasOption, JSON_OPTION_DESCRIPTION, parsePositiveInteger, writeResult, humanError, } from "../io.js";
+import { actorsOf } from "../../study/study-fields.js";
 export function registerStudyCommands(parent, io) {
     const study = parent
         .command("study")
@@ -114,7 +115,9 @@ function formatStudyShowHuman(result) {
         `id: ${config.id}`,
         `subject: ${config.subject.source}`,
         ...(config.execution?.target ? [`execution: ${config.execution.target}`] : []),
-        `actors: ${config.actors.map((actor) => actor.type).join(", ")}`,
+        `actors: ${actorsOf(config)
+            .map((actor) => actor.type)
+            .join(", ")}`,
         ...(config.title ? [`title: ${config.title}`] : []),
         ...(config.description ? [`description: ${config.description}`] : []),
         ...(result.path ? [`path: ${result.path}`] : []),

package/dist/cli/findings.d.ts

@@ -75,6 +75,11 @@ interface FindingsSource {
     loaded: LoadedAnalysis;
     /** ` --cwd <dir>` when the commands this view names need it, or "". */
     cwdFlag: string;
+    /**
+     * The project-relative path of the run's study file when that file sets `review.analysis:
+     * false`, read when the view is built. Undefined when it does not, or cannot be read.
+     */
+    analysisOffIn?: string;
 }
 /** The findings view of a run's selected analysis, or why it has none. */
 export declare function analysisFindings(source: FindingsSource): AnalysisFindings;

package/dist/cli/findings.js

@@ -7,6 +7,8 @@ import { loadAnalysis } from "../analysis/load.js";
 import { projectShareCheckedAnalysis } from "../analysis/sharing.js";
 import { loadRunBundlePrepared, resolveRunPath } from "../run/locate.js";
 import { resolvePhysicalCwd, runIdOf } from "../run/paths.js";
+import { studyProvenanceOf } from "../run/study-provenance.js";
+import { resolveStudyManifest } from "../study/discover.js";
 import { plural } from "../run/text.js";
 import { shellQuote } from "../substrates/shell.js";
 import { analysisOutcomeText, wantsJson } from "./io.js";
@@ -151,8 +153,23 @@ export function analysisFindings(source) {
     }
     if (job !== undefined || loaded.state === "invalid")
         return withoutFindings(source, "unavailable", job?.reason ?? loaded.warnings[0] ?? null, "This run's analysis records could not be read or checked, so no findings are shown.", cli(`analyze list --run ${source.runId}${source.cwdFlag}`));
+    if (source.analysisOffIn !== undefined)
+        return withoutFindings(source, "skipped", "AUTOMATIC_ANALYSIS_DISABLED", `Analysis is turned off in this run's study (review.analysis: false in ${source.analysisOffIn}), so none ran after the run. To analyze this run anyway, run the next command.`, analyzeCommand(source, undefined));
     return withoutFindings(source, "none", null, "No analysis has run for this run.", analyzeCommand(source, undefined));
 }
+/**
+ * The run's study file, project-relative, when it still names the same study and sets
+ * `review.analysis: false`. A study that turns analysis off leaves no analysis record, so the file
+ * is the only place that says why a live run has none.
+ */
+async function studyAnalysisOff(cwd, study) {
+    if (study?.path === undefined)
+        return undefined;
+    const resolved = await resolveStudyManifest(cwd, study.path).catch(() => null);
+    if (!resolved?.ok || resolved.config.id !== study.id)
+        return undefined;
+    return resolved.config.review?.analysis === false ? study.path : undefined;
+}
 /**
  * The run's bundle mode and its selected analysis: `analysisId`, or the version `analyze show`
  * defaults to. Null when the run is missing or its storage is unsafe.
@@ -163,12 +180,16 @@ export async function readRunAnalysis(cwd, run, analysisId) {
     if (!prepared)
         return null;
     const bundle = await loadRunBundlePrepared(physical, prepared).catch(() => null);
+    const analysisOffIn = bundle?.bundle.mode === "live"
+        ? await studyAnalysisOff(physical, studyProvenanceOf(bundle.bundle))
+        : undefined;
     return {
         runId: runIdOf(prepared),
         mode: bundle?.bundle.mode,
         runRoot: prepared.relativeRunRoot,
         loaded: await loadAnalysis(prepared, analysisId),
         cwdFlag: cwdFlag(cwd),
+        ...(analysisOffIn === undefined ? {} : { analysisOffIn }),
     };
 }
 /** The view of a run that could not be found. */

package/dist/cli/io.d.ts

@@ -17,7 +17,8 @@ export declare const DOTENV_OPTION_DESCRIPTION = "Load unset variables from this
 /**
  * The hidden `--env-file <path>` that `--dotenv` replaced. Node scans the whole argv for
  * `--env-file` before a script runs, and stops only at `--` (src/node_dotenv.cc), so a missing file
- * exits 9 through Node and never reaches humanish. `--dotenv` does not collide. Removed in 0.111.0.
+ * exits 9 through Node and never reaches humanish. `--dotenv` does not collide.
+ * Removed in 0.112.0: deprecated in 0.110.0 on 2026-10-03, it stays 30 days and one minor release.
  */
 export declare function envFileAliasOption(): Option;
 /** The dotenv path a command was given: `--dotenv`, or the `--env-file` alias with its warning. */

package/dist/cli/io.js

@@ -15,11 +15,12 @@ export const JSON_OPTION_DESCRIPTION = "Print a machine-readable JSON response."
 export const CWD_OPTION_DESCRIPTION = "Project directory.";
 export const RUN_OPTION_DESCRIPTION = "Run id, or latest.";
 export const DOTENV_OPTION_DESCRIPTION = "Load unset variables from this dotenv file. Values are never printed or saved.";
-const ENV_FILE_RENAMED = "`--env-file` is now `--dotenv`; `--env-file` is removed in 0.111.0.";
+const ENV_FILE_RENAMED = "`--env-file` is now `--dotenv`; `--env-file` is removed in 0.112.0.";
 /**
  * The hidden `--env-file <path>` that `--dotenv` replaced. Node scans the whole argv for
  * `--env-file` before a script runs, and stops only at `--` (src/node_dotenv.cc), so a missing file
- * exits 9 through Node and never reaches humanish. `--dotenv` does not collide. Removed in 0.111.0.
+ * exits 9 through Node and never reaches humanish. `--dotenv` does not collide.
+ * Removed in 0.112.0: deprecated in 0.110.0 on 2026-10-03, it stays 30 days and one minor release.
  */
 export function envFileAliasOption() {
     return new Option("--env-file <path>").hideHelp().conflicts("dotenv");

package/dist/cli/observer-follow.d.ts

@@ -26,8 +26,12 @@ export declare function followDecision(args: {
     follow: boolean;
     unattended: boolean;
 };
-/** The warning a command adds when it printed the Observer and exited because nobody was attached. */
-export declare function unattendedObserverWarning(command: "watch" | "observe"): string;
+/**
+ * The warning a command adds when it printed the Observer and exited because nobody was attached.
+ * It names the reason personAtTerminal found: an agent runner's marker, which can sit beside a real
+ * terminal, or no terminal at all.
+ */
+export declare function unattendedObserverWarning(command: "watch" | "observe", env?: NodeJS.ProcessEnv): string;
 /**
  * Parse --port and decide open and follow. On an invalid port it writes the failure, sets exit
  * code 2 and returns null, so a caller refuses before starting a run.

package/dist/cli/observer-follow.js

@@ -23,9 +23,17 @@ export function followDecision(args) {
     const attended = personAtTerminal();
     return { follow: attended, unattended: !attended };
 }
-/** The warning a command adds when it printed the Observer and exited because nobody was attached. */
-export function unattendedObserverWarning(command) {
-    return `No interactive terminal, so ${command} printed the Observer path and exited instead of serving it until Ctrl-C. Open the file, or pass --serve to keep serving.`;
+/**
+ * The warning a command adds when it printed the Observer and exited because nobody was attached.
+ * It names the reason personAtTerminal found: an agent runner's marker, which can sit beside a real
+ * terminal, or no terminal at all.
+ */
+export function unattendedObserverWarning(command, env = process.env) {
+    const agent = detectAgentSession(env);
+    const reason = agent === undefined
+        ? "No interactive terminal"
+        : `An agent environment was detected (${agent.marker} is set, which ${agent.runner} sets)`;
+    return `${reason}, so ${command} printed the Observer path and exited instead of serving it until Ctrl-C. Pass --serve to keep serving, or open the file.`;
 }
 /**
  * Parse --port and decide open and follow. On an invalid port it writes the failure, sets exit
@@ -112,8 +120,6 @@ export function formatObserverHuman(result) {
     ].join("\n") + "\n");
 }
 export async function followObserver(io, result, server, options = {}) {
-    io.writeOut(`watching: ${result.serverUrl ?? result.observerUrl ?? result.observerPath}\n`);
-    io.writeOut("watching: press Ctrl-C to stop\n");
     await new Promise((resolve) => {
         const signalTarget = options.signalTarget ?? process;
         const signals = options.signals ?? ["SIGINT", "SIGTERM", "SIGHUP"];
@@ -155,6 +161,10 @@ export async function followObserver(io, result, server, options = {}) {
             handlers.set(signal, handler);
             signalTarget.once(signal, handler);
         }
+        // Print the prompt only once the handlers are in place: a Ctrl-C that arrives sooner would
+        // take Node's default action and end the process without closing the server.
+        io.writeOut(`watching: ${result.serverUrl ?? result.observerUrl ?? result.observerPath}\n`);
+        io.writeOut("watching: press Ctrl-C to stop\n");
     });
 }
 export function exitCodeForSignal(signal) {