humanish 0.110.0 → 0.110.2

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

@@ -33,84 +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.
-        const command = env.hasDesktopSdk
-            ? `${HUMANISH} run try-live`
-            : env.installedInProject
-                ? `npm i -D @e2b/desktop && ${HUMANISH} run try-live`
-                : // Running from an npx cache: installing only the peer here would not be found, because
-                    // Node resolves it relative to humanish. Both, or neither.
-                    `npm i -D humanish @e2b/desktop && ${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 actors[0].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.
  *
@@ -118,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}`,
@@ -127,26 +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",
+        ...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. 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.",
-        "- A live run spends money. `execution.caps.maxUsd` in each study caps estimated model spend: the 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 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 } from "../keys/env-file.js";
+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.";
@@ -90,6 +81,7 @@ export async function applyEnvFileOption(args) {
         }
         for (const name of result.loaded)
             env[name] = stagedEnv[name];
+        recordDotenvNames(env, result.loaded);
         args.onLoaded?.({ path: args.envFile, names: result.loaded });
     }
     if (args.discoverKeys !== false) {
@@ -146,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}`]),
@@ -315,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) {

package/dist/cli/orientation.js

@@ -17,6 +17,7 @@ import { listRuns } from "../run/stored-runs.js";
 import { plural } from "../run/text.js";
 import { supportsLocalBrowser } from "./first-run-path.js";
 import { PRODUCT_SENTENCE } from "./product-sentence.js";
+import { cli } from "./invocation.js";
 export const ORIENTATION_SCHEMA = "humanish.orientation.v1";
 /**
  * Read the project's state. Pure-ish: it only reads, never writes, and never touches the network or
@@ -69,7 +70,7 @@ function nextCommandsFor(args) {
             ? []
             : [
                 {
-                    command: "humanish migrate --dry-run",
+                    command: cli("migrate --dry-run"),
                     why: `${plural(v2, "study file")} ${v2 === 1 ? "uses" : "use"} humanish.lab.v2, which humanish no longer reads; this lists the conversion, and humanish migrate writes it`,
                 },
             ]),
@@ -77,41 +78,42 @@ function nextCommandsFor(args) {
             ? []
             : [
                 {
-                    command: "humanish study list",
+                    command: cli("study list"),
                     why: `${plural(moved, "study file")} ${moved === 1 ? "is" : "are"} in a labs/ directory, which humanish no longer reads; this names each one and the studies/ directory to move it to`,
                 },
             ]),
     ];
-    // A fix that is already `humanish study list` replaces the plain suggestion of the same command.
+    // A fix that is already `study list` replaces the plain suggestion of the same command.
     const named = new Set(fixes.map((fix) => fix.command));
     return [...fixes, ...nextCommandsForStudies(args).filter((next) => !named.has(next.command))];
 }
 function nextCommandsForStudies(args) {
     const dryRun = {
-        command: "humanish run first-run",
+        command: cli("run first-run"),
         why: "a dry run: no browser or model runs, no keys, no spend",
     };
     if (!args.initialized) {
         return [
             {
-                command: "humanish init --yes",
+                command: cli("init --yes"),
                 why: "write starter studies, personas and an AGENTS.md (--dry-run lists every file first)",
             },
             dryRun,
         ];
     }
-    // The starter live study this host can run. The other starter studies are templates whose subject
-    // still names your-org/your-app, so they are never suggested.
+    // The starter live study this host can run: the hosted try-live study first, since it needs no
+    // local Docker or VM, then the local one where the host shape supports it. The other starter
+    // studies are templates whose subject still names your-org/your-app, so they are never suggested.
     const liveStudy = (supportsLocalBrowser(args.host.platform, args.host.arch)
-        ? ["local-browser", "try-live"]
+        ? ["try-live", "local-browser"]
         : ["try-live"]).find((id) => args.studyIds.includes(id));
     if (!args.hasRun) {
         return [
             dryRun,
             liveStudy === undefined
-                ? { command: "humanish study list", why: "see the studies this project declares" }
+                ? { command: cli("study list"), why: "see the studies this project declares" }
                 : {
-                    command: `humanish doctor --study ${liveStudy}`,
+                    command: cli(`doctor --study ${liveStudy}`),
                     why: `check what the ${liveStudy} study still needs before a live run`,
                 },
         ];
@@ -119,12 +121,12 @@ function nextCommandsForStudies(args) {
     return [
         ...(liveStudy === undefined
             ? []
-            : [{ command: `humanish run ${liveStudy}`, why: "run a real participant against an app" }]),
+            : [{ command: cli(`run ${liveStudy}`), why: "run a real participant against an app" }]),
         {
-            command: "humanish verify --run latest",
+            command: cli("verify --run latest"),
             why: "check the last run's evidence and public-safety gates",
         },
-        { command: "humanish observe --run latest", why: "reopen the last run's Observer" },
+        { command: cli("observe --run latest"), why: "reopen the last run's Observer" },
     ];
 }
 /**
@@ -151,6 +153,6 @@ export function formatOrientationHuman(state) {
         lines.push(`      ${next.why}`);
     }
     lines.push("");
-    lines.push("`humanish --help` lists every command.");
+    lines.push(`\`${cli("--help")}\` lists every command.`);
     return `${lines.join("\n")}\n`;
 }

package/dist/cli/product-sentence.d.ts

@@ -1,6 +1,6 @@
 /**
- * The product in one sentence. Line 3 of `README.md`, package.json's description, `humanish --help`,
- * bare `humanish` and the humanish skill all use it; tests/cli/product-sentence.test.ts holds them
- * equal.
+ * The product in one sentence. package.json's description, `humanish --help` and bare `humanish`
+ * use it, and line 3 of `README.md` and the humanish skill's description open with it;
+ * tests/cli/product-sentence.test.ts holds them equal.
  */
 export declare const PRODUCT_SENTENCE = "Synthetic user research for apps, CLIs, and agent-facing product flows.";

package/dist/cli/product-sentence.js

@@ -1,6 +1,6 @@
 /**
- * The product in one sentence. Line 3 of `README.md`, package.json's description, `humanish --help`,
- * bare `humanish` and the humanish skill all use it; tests/cli/product-sentence.test.ts holds them
- * equal.
+ * The product in one sentence. package.json's description, `humanish --help` and bare `humanish`
+ * use it, and line 3 of `README.md` and the humanish skill's description open with it;
+ * tests/cli/product-sentence.test.ts holds them equal.
  */
 export const PRODUCT_SENTENCE = "Synthetic user research for apps, CLIs, and agent-facing product flows.";

package/dist/cli/version.d.ts

@@ -0,0 +1 @@
+export declare const CLI_VERSION: string;

package/dist/cli/version.js

@@ -0,0 +1,11 @@
+import { readFileSync } from "node:fs";
+import { dirname, resolve } from "node:path";
+import { fileURLToPath } from "node:url";
+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();

package/dist/evidence/encoded-text.d.ts

@@ -1,5 +1,12 @@
 /** Undoes JSON and JS escapes, percent-encoding and HTML character references, one pass each. */
 export declare function decodeEscapes(text: string): string;
+/** How scanEncodedText reads text. */
+export interface EncodedTextScanOptions {
+    /** Do not count an encoded binary run as opaque. */
+    readonly allowOpaqueBase64?: boolean;
+    /** Match secret shapes only, leaving local paths out, as a URL's path may look like one. */
+    readonly secretsOnly?: boolean;
+}
 export interface EncodedTextScan {
     /** A secret or private path, in the text or in a decoding of it. */
     readonly sensitive: boolean;
@@ -12,9 +19,7 @@ export interface EncodedTextScan {
  * turn. A run that decodes to an archive, or to other binary past MIN_OPAQUE_BASE64_RUN characters,
  * is opaque unless the caller allows opaque runs.
  */
-export declare function scanEncodedText(text: string, options?: {
-    allowOpaqueBase64?: boolean;
-}, depth?: number): EncodedTextScan;
+export declare function scanEncodedText(text: string, options?: EncodedTextScanOptions, depth?: number): EncodedTextScan;
 /**
  * scanEncodedText, cached in this process. The key is the sha256 of the scanned string's UTF-16
  * code units, the options and ENCODED_SCAN_VERSION. Encoding as UTF-16LE keeps every code unit,
@@ -22,6 +27,4 @@ export declare function scanEncodedText(text: string, options?: {
  * scan of the same string would give. Repeated verifies of an unchanged file, as serve admission
  * and the Observer render do, skip the scan.
  */
-export declare function scanEncodedTextCached(text: string, options?: {
-    allowOpaqueBase64?: boolean;
-}): EncodedTextScan;
+export declare function scanEncodedTextCached(text: string, options?: EncodedTextScanOptions): EncodedTextScan;