humanish 0.110.1 → 0.110.2

package/dist/cli/findings.js

@@ -10,6 +10,7 @@ import { resolvePhysicalCwd, runIdOf } from "../run/paths.js";
 import { plural } from "../run/text.js";
 import { shellQuote } from "../substrates/shell.js";
 import { analysisOutcomeText, wantsJson } from "./io.js";
+import { cli } from "./invocation.js";
 export const ANALYSIS_FINDINGS_SCHEMA = "humanish.analysis-findings.v1";
 /** ` --cwd <dir>`, or "" when `cwd` is the current directory. */
 function cwdFlag(cwd) {
@@ -18,7 +19,7 @@ function cwdFlag(cwd) {
     return ` --cwd ${/^[\w@%+=:,./-]+$/.test(cwd) ? cwd : shellQuote(cwd)}`;
 }
 function analyzeCommand(source, provider) {
-    const run = `humanish analyze --run ${source.runId}${source.cwdFlag}`;
+    const run = cli(`analyze --run ${source.runId}${source.cwdFlag}`);
     return provider === "codex"
         ? `${run} --provider codex`
         : `${run} --max-cost ${DEFAULT_ANALYSIS_MAX_COST_USD}`;
@@ -132,10 +133,10 @@ export function analysisFindings(source) {
         };
     }
     if (loaded.warnings.includes("ANALYSIS_SENSITIVE_TEXT_QUARANTINED"))
-        return withoutFindings(source, "unavailable", "ANALYSIS_SENSITIVE_TEXT_QUARANTINED", `The analysis text matched a sensitive-text pattern, so it is not printed. humanish analyze show --run ${source.runId}${source.cwdFlag} --json prints the raw record.`, null);
+        return withoutFindings(source, "unavailable", "ANALYSIS_SENSITIVE_TEXT_QUARANTINED", `The analysis text matched a sensitive-text pattern, so it is not printed. ${cli(`analyze show --run ${source.runId}${source.cwdFlag} --json`)} prints the raw record.`, null);
     const job = loaded.automatic;
     if (job?.state === "queued" || job?.state === "running")
-        return withoutFindings(source, "running", null, "The automatic analysis is still running. Check again when it finishes.", `humanish review --run ${source.runId}${source.cwdFlag}`);
+        return withoutFindings(source, "running", null, "The automatic analysis is still running. Check again when it finishes.", cli(`review --run ${source.runId}${source.cwdFlag}`));
     if (analysis && analysis.result === null)
         return withoutFindings(source, "failed", analysis.error, `Analysis attempt ${analysis.id} ${analysis.status === "cancelled" ? "was cancelled" : "failed"}${analysis.error ? ` (${analysis.error})` : ""} and left no findings.`, analyzeCommand(source, analysis.provider));
     if (job?.state === "failed" || job?.state === "cancelled") {
@@ -149,7 +150,7 @@ export function analysisFindings(source) {
             : `${analyzeCommand(source, undefined)}${refused ? " --dry-run" : ""}`);
     }
     if (job !== undefined || loaded.state === "invalid")
-        return withoutFindings(source, "unavailable", job?.reason ?? loaded.warnings[0] ?? null, "This run's analysis records could not be read or checked, so no findings are shown.", `humanish analyze list --run ${source.runId}${source.cwdFlag}`);
+        return withoutFindings(source, "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}`));
     return withoutFindings(source, "none", null, "No analysis has run for this run.", analyzeCommand(source, undefined));
 }
 /**
@@ -179,7 +180,7 @@ export function missingRunFindings(cwd, run) {
         warnings: ["ANALYSIS_RUN_NOT_FOUND"],
     };
     const flag = cwdFlag(cwd);
-    return withoutFindings({ runId: run, mode: undefined, runRoot: "", loaded, cwdFlag: flag }, "unavailable", "ANALYSIS_RUN_NOT_FOUND", `Run ${run} was not found or its storage is unsafe.`, `humanish runs${flag}`);
+    return withoutFindings({ runId: run, mode: undefined, runRoot: "", loaded, cwdFlag: flag }, "unavailable", "ANALYSIS_RUN_NOT_FOUND", `Run ${run} was not found or its storage is unsafe.`, cli(`runs${flag}`));
 }
 /** The findings of a run's selected analysis, or why it has none. */
 export async function readRunFindings(cwd, run, analysisId) {
@@ -307,7 +308,7 @@ export async function writeRunFindings(command, io, cwd, result) {
         return;
     try {
         const view = await readRunFindings(cwd, result.runId, analysisId);
-        const full = `humanish review --run ${view.runId}${cwdFlag(cwd)}`;
+        const full = cli(`review --run ${view.runId}${cwdFlag(cwd)}`);
         io.writeOut(`${formatFindingsSummary(view, full).join("\n")}\n`);
     }
     catch {

package/dist/cli/first-run-path.d.ts

@@ -25,10 +25,25 @@ export interface FirstRunEnvironment {
     hasProviderKey: boolean;
     /** The coding agents already signed in locally: Codex, Claude Code, or both. */
     localAgents: readonly SignedInAgent[];
-    /** Host shape only; `doctor --study local-browser` owns exact read-only readiness. */
+    /**
+     * init's quick read of this host for a local browser study: Linux x64 with `/dev/kvm`,
+     * `/dev/net/tun` and Docker,
+     * or an M3-or-newer Mac. Undefined when it was not read. `doctor --study local-browser` owns the
+     * full check.
+     */
+    localBrowserHost?: LocalBrowserHost;
+    /** Host shape only, for the prerequisites a local step names. */
     platform?: NodeJS.Platform;
-    arch?: string;
+    /** How a suggested command invokes humanish; `npx humanish` when unset. */
+    humanish?: string;
 }
+/** Whether this host passed init's quick checks for a local browser study, and why not. */
+export type LocalBrowserHost = {
+    ok: true;
+} | {
+    ok: false;
+    reason: string;
+};
 export type FirstRunActor = "openai-computer-use" | "local-agent";
 /**
  * Which brain the starter live study should be written for. A machine with a signed-in coding agent
@@ -41,7 +56,7 @@ export declare function starterActorFor(env: FirstRunEnvironment): FirstRunActor
  * refuse to run on a machine where only Claude Code is signed in.
  */
 export declare function starterLocalAgentFor(env: FirstRunEnvironment): LocalAgentId | undefined;
-/** Hosts that run local browser studies: Linux x64 and Apple Silicon Macs. */
+/** Host shapes the local browser route is built for: Linux x64 and Apple Silicon Macs. */
 export declare function supportsLocalBrowser(platform: NodeJS.Platform | undefined, arch: string | undefined): boolean;
 export interface FirstRunStep {
     /** The exact command to run. */
@@ -50,14 +65,18 @@ export interface FirstRunStep {
     why: string;
 }
 /**
- * The next one or two commands, in order. Deliberately short: a list of twelve options is the same
- * as no guidance, and the reader here has just been handed twenty files.
+ * The next two or three commands, in order: the dry run, the hosted try-live study when keys or a
+ * signed-in agent allow it, and the local browser study where this host passed its quick checks.
+ * Deliberately short: a list of twelve options is the same as no guidance, and the reader here has
+ * just been handed a directory of new files.
  */
 export declare function firstRunSteps(env: FirstRunEnvironment): FirstRunStep[];
 /** The block init prints after its changes. */
 export declare function firstRunGuidance(env: FirstRunEnvironment): string[];
-/** Lets init recognise its own section without rewriting a file someone else wrote. */
+/** Starts humanish's section of `AGENTS.md`, on its heading line. */
 export declare const AGENTS_SECTION_MARKER = "<!-- humanish:agents-guide -->";
+/** Ends humanish's section, so init can replace the section and nothing after it. */
+export declare const AGENTS_SECTION_END_MARKER = "<!-- /humanish:agents-guide -->";
 /**
  * What the next coding agent needs to know about humanish in this project.
  *
@@ -65,6 +84,7 @@ export declare const AGENTS_SECTION_MARKER = "<!-- humanish:agents-guide -->";
  * read on arrival. Increasingly the thing that ran `humanish init` was itself an agent working for
  * someone, and the agent that shows up tomorrow finds a `humanish/` directory with no idea what it
  * is for. Deliberately short and command-first, because an agent acts on the commands it is given.
+ * Commands use `humanish`, the prefix init chose for where humanish is installed.
  */
-export declare function agentsSection(): string;
+export declare function agentsSection(humanish?: string): string;
 export {};

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

@@ -33,87 +33,111 @@ function preferredAgent(env) {
 export function starterLocalAgentFor(env) {
     return starterActorFor(env) === "local-agent" ? preferredAgent(env)?.id : undefined;
 }
-/**
- * How each hint invokes the CLI. \`npx humanish\` works from a project install and from an npx cache;
- * a dev-dependency install puts no \`humanish\` on \`PATH\`, so a bare name can reach a stale global one.
- */
-const HUMANISH = "npx humanish";
-/** Hosts that run local browser studies: Linux x64 and Apple Silicon Macs. */
+/** Host shapes the local browser route is built for: Linux x64 and Apple Silicon Macs. */
 export function supportsLocalBrowser(platform, arch) {
     return (platform === "linux" && arch === "x64") || (platform === "darwin" && arch === "arm64");
 }
 /**
- * The next one or two commands, in order. Deliberately short: a list of twelve options is the same
- * as no guidance, and the reader here has just been handed twenty files.
+ * The next two or three commands, in order: the dry run, the hosted try-live study when keys or a
+ * signed-in agent allow it, and the local browser study where this host passed its quick checks.
+ * Deliberately short: a list of twelve options is the same as no guidance, and the reader here has
+ * just been handed a directory of new files.
  */
 export function firstRunSteps(env) {
+    const humanish = env.humanish ?? "npx humanish";
     const steps = [
         {
-            command: `${HUMANISH} run first-run`,
+            command: `${humanish} run first-run`,
             why: "a dry run: no browser or model runs, no keys, no spend",
         },
     ];
-    if (supportsLocalBrowser(env.platform, env.arch)) {
-        const prerequisites = env.platform === "darwin"
-            ? "M3-or-newer Mac, native ARM64 Node, Lima 2.2+, and a supported signed-in Codex CLI"
-            : "local rootful Docker, KVM, TUN, and a supported signed-in Codex CLI";
-        steps.push({
-            command: `${HUMANISH} doctor --study local-browser`,
-            why: `check the local browser study (${prerequisites}); no resources or quota used. Run \`${HUMANISH} runtime setup\` to prepare it, then start your app and run \`${HUMANISH} run local-browser\`; no E2B or model API key`,
-        });
-        return steps;
+    const local = localBrowserStep(env, humanish);
+    const hostedRunnable = env.hasE2bKey && (env.hasProviderKey || env.localAgents.length > 0);
+    if (hostedRunnable) {
+        steps.push(hostedStep(env, humanish, ""));
+        if (local !== undefined)
+            steps.push(local);
     }
-    const localUnavailable = env.platform === undefined
-        ? ""
-        : " Local browsers are unavailable on this host; they support Linux x64 or M3-or-newer Apple Silicon Macs.";
-    if (!env.hasE2bKey) {
-        steps.push({
-            command: `${HUMANISH} keys set e2b`,
-            why: `the hosted starter needs an E2B desktop.${localUnavailable}`,
-        });
-        return steps;
+    else if (local !== undefined) {
+        steps.push(local);
     }
-    if (env.hasProviderKey || env.localAgents.length > 0) {
-        const brain = env.hasProviderKey
-            ? "your provider key"
-            : `${preferredAgent(env)?.label} (already signed in, so no API key is needed)`;
-        // Everything the step needs, in one line. Splitting it across two commands means the second
-        // one fails, which is the same dead end this guidance exists to remove.
-        if (!env.hasDesktopSdk && env.desktopPeerCommand === undefined) {
-            steps.push({
-                command: `${HUMANISH} doctor`,
-                why: "the hosted starter needs the desktop SDK, and installing it from here would remove what this directory's node_modules holds; doctor names the command to run from your project's directory",
-            });
-            return steps;
-        }
-        const command = env.hasDesktopSdk
-            ? `${HUMANISH} run try-live`
-            : `${env.desktopPeerCommand} && ${HUMANISH} run try-live`;
-        steps.push({
-            command,
-            why: `a live study: one participant drives a real app in a hosted desktop, using ${brain}` +
-                (env.hasDesktopSdk ? "" : " (the desktop SDK is an optional peer, so it installs first)") +
-                (!env.hasProviderKey
-                    ? "; automatic findings analysis is skipped without OPENAI_API_KEY"
-                    : "") +
-                localUnavailable,
-        });
-        return steps;
+    else {
+        steps.push(hostedStep(env, humanish, localUnavailableNote(env)));
     }
-    steps.push({
-        command: `${HUMANISH} keys set openai`,
-        why: "openai-computer-use needs an API key; to use a Codex or Claude Code login instead, sign in and change the study to actor.type: local-agent" +
-            localUnavailable,
-    });
     return steps;
 }
+/** The local browser step, where the host passed init's checks and Codex is signed in. */
+function localBrowserStep(env, humanish) {
+    if (env.localBrowserHost?.ok !== true)
+        return undefined;
+    if (!env.localAgents.some((agent) => agent.id === "codex"))
+        return undefined;
+    const prerequisites = env.platform === "darwin"
+        ? "native ARM64 Node, Lima 2.2+, and a supported signed-in Codex CLI"
+        : "local rootful Docker, KVM, TUN, and a supported signed-in Codex CLI";
+    return {
+        command: `${humanish} doctor --study local-browser`,
+        why: `check the local browser study (${prerequisites}); no resources or quota used. Run \`${humanish} runtime setup\` to prepare it, then start your app and run \`${humanish} run local-browser\`; no E2B or model API key`,
+    };
+}
+/** Why the local route is not offered, appended to a key step so the reader knows it was considered. */
+function localUnavailableNote(env) {
+    const host = env.localBrowserHost;
+    if (host === undefined)
+        return "";
+    if (!host.ok)
+        return ` Local browser studies are unavailable on this host: ${host.reason}.`;
+    return " A local browser study also runs on this host once Codex is signed in (`codex login`).";
+}
+/** The hosted try-live step, or the key or setup step it still needs. */
+function hostedStep(env, humanish, note) {
+    if (!env.hasE2bKey) {
+        return {
+            command: `${humanish} keys set e2b`,
+            why: `the hosted starter needs an E2B desktop.${note}`,
+        };
+    }
+    if (!env.hasProviderKey && env.localAgents.length === 0) {
+        return {
+            command: `${humanish} keys set openai`,
+            why: "openai-computer-use needs an API key; to use a Codex or Claude Code login instead, sign in and change the study to actor.type: local-agent." +
+                note,
+        };
+    }
+    const brain = env.hasProviderKey
+        ? "your provider key"
+        : `${preferredAgent(env)?.label} (already signed in, so no API key is needed)`;
+    // Everything the step needs, in one line. Splitting it across two commands means the second
+    // one fails, which is the same dead end this guidance exists to remove.
+    if (!env.hasDesktopSdk && env.desktopPeerCommand === undefined) {
+        return {
+            command: `${humanish} doctor`,
+            why: "the hosted starter needs the desktop SDK, and installing it from here would remove what this directory's node_modules holds; doctor names the command to run from your project's directory",
+        };
+    }
+    // After the peer install, humanish is a dependency of this project, where `npx humanish` finds it.
+    const command = env.hasDesktopSdk
+        ? `${humanish} run try-live`
+        : `${env.desktopPeerCommand} && npx humanish run try-live`;
+    return {
+        command,
+        why: `a live study: one participant drives a real app in a hosted desktop, using ${brain}` +
+            (env.hasDesktopSdk ? "" : " (the desktop SDK is an optional peer, so it installs first)") +
+            (!env.hasProviderKey
+                ? "; automatic findings analysis is skipped without OPENAI_API_KEY"
+                : "") +
+            note,
+    };
+}
 /** The block init prints after its changes. */
 export function firstRunGuidance(env) {
     const steps = firstRunSteps(env);
     return ["", "next:", ...steps.flatMap((step) => [`  ${step.command}`, `      ${step.why}`])];
 }
-/** Lets init recognise its own section without rewriting a file someone else wrote. */
+/** Starts humanish's section of `AGENTS.md`, on its heading line. */
 export const AGENTS_SECTION_MARKER = "<!-- humanish:agents-guide -->";
+/** Ends humanish's section, so init can replace the section and nothing after it. */
+export const AGENTS_SECTION_END_MARKER = "<!-- /humanish:agents-guide -->";
 /**
  * What the next coding agent needs to know about humanish in this project.
  *
@@ -121,8 +145,23 @@ export const AGENTS_SECTION_MARKER = "<!-- humanish:agents-guide -->";
  * read on arrival. Increasingly the thing that ran `humanish init` was itself an agent working for
  * someone, and the agent that shows up tomorrow finds a `humanish/` directory with no idea what it
  * is for. Deliberately short and command-first, because an agent acts on the commands it is given.
+ * Commands use `humanish`, the prefix init chose for where humanish is installed.
  */
-export function agentsSection() {
+export function agentsSection(humanish = "npx humanish") {
+    const commands = [
+        ["study list --json", "the studies in this project"],
+        ["run first-run --no-open", "dry run: no browser, model, keys, or spend"],
+        ["doctor --study try-live", "what the hosted starter study still needs"],
+        [
+            "run try-live --no-open",
+            "demo app study: E2B plus the selected participant's authentication",
+        ],
+        ["doctor --study local-browser", "local Docker/Firecracker + Codex-account readiness"],
+        ["run local-browser --no-open", "your loopback app; no E2B or model API key"],
+        ["verify --run <id> --json", "is the evidence share-safe"],
+        ["review --run <id>", "the run's outcome and its analysis findings"],
+    ];
+    const width = Math.max(...commands.map(([command]) => command.length));
     return [
         "",
         `## humanish ${AGENTS_SECTION_MARKER}`,
@@ -130,30 +169,28 @@ export function agentsSection() {
         "This project uses humanish: synthetic participants use the product and leave evidence.",
         "",
         "```bash",
-        "humanish doctor --study try-live  # requirements for the selected participant and analysis",
-        "humanish study list --json # the studies in this project",
-        "humanish run first-run     # dry run: no browser, model, keys, or spend",
-        "humanish doctor --study local-browser  # local Docker/Firecracker + Codex-account readiness",
-        "humanish run local-browser # your loopback app; no E2B or model API key",
-        "humanish run try-live      # demo app study: E2B plus the selected participant's authentication",
-        "humanish verify --run latest --json   # is the evidence share-safe",
-        "humanish review --run <id>  # the run's outcome and its analysis findings",
+        ...commands.map(([command, why]) => `${humanish} ${command.padEnd(width)}  # ${why}`),
         "```",
         "",
-        "- After a live run, run `humanish review --run <id>` (or `--json`) and report its findings to the",
-        "  person you are working for: each one's title, impact, confidence, recovery and cited captures.",
-        "  When it shows no findings, report its message and the command it names.",
+        `- After a live run, run \`${humanish} review --run <id>\` (or \`--json\`) and report its findings`,
+        "  to the person you are working for: each one's title, impact, confidence, recovery and cited",
+        "  captures. When it shows no findings, report its message and the command it names. Every run",
+        "  prints its id; `latest` moves with each run, dry runs included.",
         "- Studies are declared in `humanish/studies/*.yaml`. Edit `try-live.yaml`'s `subject` to point",
         "  at this project's own app once you have seen a run work.",
-        "- Configure the local study without editing YAML: `humanish init --yes --local-browser",
+        `- Configure the local study without editing YAML: \`${humanish} init --yes --local-browser`,
         '  http://127.0.0.1:3000 --local-mission "Complete the primary flow"` on first setup.',
         "- Evidence lands in gitignored `.humanish/runs/`. Never commit it, and never paste raw run",
-        "  bundles into an issue; `humanish feedback issue` writes a redacted, share-safe draft.",
-        "- `humanish tui` is for people and refuses to run in an agent session. Use the `--json`",
-        "  commands above instead, and tell the person you are working for that `humanish tui` exists.",
+        `  bundles into an issue; \`${humanish} feedback issue\` writes a redacted, share-safe draft.`,
+        `- \`${humanish} tui\` is for people and refuses to run in an agent session. Use the commands`,
+        "  above instead, and tell the person you are working for that the TUI exists.",
         "- A live run spends money. `caps.maxUsd` in each study caps estimated model spend: the run",
         "  stops before its next request once the estimate passes it, so the last request can go over, and",
         "  hosted desktop time is billed on top. Do not raise it without asking the person you are working for.",
+        `- \`${humanish} init --yes\` rewrites this section, between its two markers, to match the installed`,
+        "  humanish. Write your own notes outside it.",
+        "",
+        AGENTS_SECTION_END_MARKER,
         "",
     ].join("\n");
 }

package/dist/cli/invocation.d.ts

@@ -0,0 +1,7 @@
+import { type HumanishInstall } from "../substrates/e2b/peer-install.js";
+/** The prefix for a suggested command, by install. */
+export declare function invocationFor(install: HumanishInstall, version: string): string;
+/** How this process's suggested commands invoke humanish, read once per process. */
+export declare function humanishCommand(): string;
+/** A suggested command: `cli("review --run x")` is `npx humanish review --run x` in a project. */
+export declare function cli(rest: string): string;

package/dist/cli/invocation.js

@@ -0,0 +1,32 @@
+// How the commands humanish suggests should invoke humanish, chosen from where the running copy is
+// installed. A dev-dependency install puts no `humanish` on `PATH`, so a bare name there reaches a
+// stale global install when one exists, or nothing. `npx humanish` with no version, run where no
+// project declares humanish, also resolves a global install before it fetches one. A one-shot run
+// therefore names its own version, so the next command runs the same CLI.
+import { humanishInstall } from "../substrates/e2b/peer-install.js";
+import { CLI_VERSION } from "./version.js";
+/** The prefix for a suggested command, by install. */
+export function invocationFor(install, version) {
+    switch (install.kind) {
+        case "project":
+        case "other":
+            return "npx humanish";
+        case "one-shot":
+            return `npx humanish@${version}`;
+        // A global install is on `PATH`. A source checkout runs through a link or `pnpm humanish`, and
+        // keeping the bare name there keeps test output the same on every machine.
+        case "global":
+        case "checkout":
+            return "humanish";
+    }
+}
+let cached;
+/** How this process's suggested commands invoke humanish, read once per process. */
+export function humanishCommand() {
+    cached ??= invocationFor(humanishInstall(), CLI_VERSION);
+    return cached;
+}
+/** A suggested command: `cli("review --run x")` is `npx humanish review --run x` in a project. */
+export function cli(rest) {
+    return `${humanishCommand()} ${rest}`;
+}

package/dist/cli/io.d.ts

@@ -3,7 +3,7 @@ import { discoverProviderKeys, type DotenvLoad } from "../keys/key-resolution.js
 import { type TelemetryProperties } from "./telemetry.js";
 import type { RunResult } from "../run/results.js";
 export declare const CLI_RESPONSE_SCHEMA = "humanish.cli-response.v1";
-export declare const CLI_VERSION: string;
+export { CLI_VERSION } from "./version.js";
 export interface CliIo {
     writeOut(text: string): void;
     writeErr(text: string): void;
@@ -41,6 +41,8 @@ export interface StudyCommandOptions {
     port?: string | undefined;
     rerunFailedFrom?: string | undefined;
     runId?: string | undefined;
+    /** watch only: serve and follow the Observer even without an interactive terminal. */
+    serve?: boolean | undefined;
     /** Repo-relative path to an adopter scorer module; overrides review.scorer.ref when set. */
     scorer?: string | undefined;
     expose?: boolean | undefined;

package/dist/cli/io.js

@@ -1,23 +1,14 @@
 import { automaticAnalysisSucceeded, defaultAnalysisOverBudget, } from "../analysis/automatic-completion.js";
 import { DEFAULT_ANALYSIS_MAX_COST_USD } from "../analysis/automatic-config.js";
-import { readFileSync } from "node:fs";
-import { dirname, resolve } from "node:path";
-import { fileURLToPath } from "node:url";
 import { Command, Option } from "commander";
 import { loadEnvFile, recordDotenvNames } from "../keys/env-file.js";
 import { discoverProviderKeys } from "../keys/key-resolution.js";
 import { deriveRunFacts } from "./telemetry.js";
 import { warnAndQueue, withQueuedWarnings } from "./deprecations.js";
 import { forTerminal } from "../routes/terminal/encoding.js";
+import { cli } from "./invocation.js";
 export const CLI_RESPONSE_SCHEMA = "humanish.cli-response.v1";
-function readCliVersion() {
-    const packageJsonPath = resolve(dirname(fileURLToPath(import.meta.url)), "..", "..", "package.json");
-    const packageJson = JSON.parse(readFileSync(packageJsonPath, "utf8"));
-    return typeof packageJson.version === "string" && packageJson.version.trim()
-        ? packageJson.version
-        : "0.0.0";
-}
-export const CLI_VERSION = readCliVersion();
+export { CLI_VERSION } from "./version.js";
 // One text per shared flag, so the same flag reads the same on every command.
 // tests/cli/shared-options.test.ts walks the program and holds every use to these.
 export const JSON_OPTION_DESCRIPTION = "Print a machine-readable JSON response.";
@@ -147,11 +138,12 @@ export function parseParticipantIds(value) {
  * command: the run-not-found and missing-study messages do.
  */
 const NEXT_COMMAND = {
-    HUMANISH_STUDY_NOT_FOUND: "humanish study list",
+    HUMANISH_STUDY_NOT_FOUND: "study list",
 };
 /** `<command> failed: <message>`, then `code: <CODE>`, then `next: <command>` when one is known. */
 export function formatCliError(command, error) {
-    const next = error.code === undefined ? undefined : NEXT_COMMAND[error.code];
+    const rest = error.code === undefined ? undefined : NEXT_COMMAND[error.code];
+    const next = rest === undefined ? undefined : cli(rest);
     return ([
         `${command} failed: ${error.message}`,
         ...(error.code === undefined ? [] : [`code: ${error.code}`]),
@@ -316,7 +308,7 @@ function overBudgetAnalysisHint(result) {
     const estimate = result.automaticAnalysis?.result?.admission?.estimatedCostUsd ?? null;
     const suggested = Math.ceil(estimate ?? DEFAULT_ANALYSIS_MAX_COST_USD + 1);
     const shown = estimate === null ? "" : ` ($${estimate.toFixed(2)})`;
-    return `analysis: its estimate${shown} is over the default $${DEFAULT_ANALYSIS_MAX_COST_USD} cap, so no request was sent. To analyze this run: humanish analyze --run ${result.runId ?? "latest"} --max-cost ${suggested}\n`;
+    return `analysis: its estimate${shown} is over the default $${DEFAULT_ANALYSIS_MAX_COST_USD} cap, so no request was sent. To analyze this run: ${cli(`analyze --run ${result.runId ?? "latest"} --max-cost ${suggested}`)}\n`;
 }
 export function automaticAnalysisEnvelope(result) {
     if (result === null ||

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

@@ -8,7 +8,26 @@ export interface ObserverPlan {
     /** Open the page: the served URL when following, the static file otherwise. */
     shouldOpen: boolean;
     wantsFollow: boolean;
+    /** Set when the command would have followed, but nobody is at a terminal to stop it. */
+    unattended?: boolean;
 }
+/**
+ * Whether a person can stop a served Observer: stdin and stdout are terminals, and no agent runner
+ * claims the session. An agent's shell or a pipe has nobody to press Ctrl-C, so a server there
+ * waits forever. A TTY alone is not enough, since Codex gives the commands it runs a terminal.
+ */
+export declare function personAtTerminal(env?: NodeJS.ProcessEnv): boolean;
+/** Whether `watch` or `observe` serves the Observer and stays attached. */
+export declare function followDecision(args: {
+    wantsMachine: boolean;
+    detach?: boolean | undefined;
+    serve?: boolean | undefined;
+}): {
+    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;
 /**
  * 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.
@@ -20,6 +39,7 @@ export declare function planObserver(args: {
     io: CliIo;
     open?: boolean | undefined;
     port: string;
+    serve?: boolean | undefined;
 }): ObserverPlan | null;
 /** The `open` a run's static Observer render takes: a followed Observer opens its served URL. */
 export declare function staticObserverOpen(plan: ObserverPlan): boolean;

package/dist/cli/observer-follow.js

@@ -1,6 +1,32 @@
 import { Command } from "commander";
 import { serveObserver } from "../observer/render.js";
+import { detectAgentSession } from "../actors/agent-session.js";
 import { formatRunHuman, parseObserverPort, wantsJson, writeResult, humanError, } from "./io.js";
+/**
+ * Whether a person can stop a served Observer: stdin and stdout are terminals, and no agent runner
+ * claims the session. An agent's shell or a pipe has nobody to press Ctrl-C, so a server there
+ * waits forever. A TTY alone is not enough, since Codex gives the commands it runs a terminal.
+ */
+export function personAtTerminal(env = process.env) {
+    return (process.stdin.isTTY === true &&
+        process.stdout.isTTY === true &&
+        detectAgentSession(env) === undefined);
+}
+/** Whether `watch` or `observe` serves the Observer and stays attached. */
+export function followDecision(args) {
+    if (args.detach === true)
+        return { follow: false, unattended: false };
+    if (args.serve === true)
+        return { follow: true, unattended: false };
+    if (args.wantsMachine)
+        return { follow: false, unattended: false };
+    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.`;
+}
 /**
  * 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.
@@ -28,7 +54,13 @@ export function planObserver(args) {
         : args.open === true
             ? true
             : !wantsMachine && process.stdout.isTTY === true;
-    return { port, shouldOpen, wantsFollow: !wantsMachine && args.detach !== true };
+    const decision = followDecision({ wantsMachine, detach: args.detach, serve: args.serve });
+    return {
+        port,
+        shouldOpen,
+        wantsFollow: decision.follow,
+        ...(decision.unattended ? { unattended: true } : {}),
+    };
 }
 /** The `open` a run's static Observer render takes: a followed Observer opens its served URL. */
 export function staticObserverOpen(plan) {
@@ -43,6 +75,9 @@ export async function showObserver(args) {
         server = await serveObserver(rendered, { open: plan.shouldOpen, port: plan.port });
         result = withObserverServer(rendered, server);
     }
+    else if (rendered.ok && plan.unattended === true) {
+        result = { ...rendered, warnings: [...rendered.warnings, unattendedObserverWarning("watch")] };
+    }
     writeResult(args.command, args.io, result, formatObserverHuman);
     args.io.setExitCode(result.ok ? 0 : 2);
     if (result.ok && server) {