humanish 0.104.3 → 0.106.0

package/dist/cli/doctor.js

@@ -0,0 +1,263 @@
+import { readFile } from "node:fs/promises";
+import { existsSync } from "node:fs";
+import path from "node:path";
+import { probeKeySources, } from "../keys/key-resolution.js";
+import { nodeSupportsTui, terminalSurfaceMessage, TUI_BUNDLE_URL } from "../tui/contract.js";
+import { detectLocalAgents, localAgentDoctorMessage, } from "../actors/local-agent/cli.js";
+import { labSetupChecks } from "../lab/doctor.js";
+import { prepareSelectedOutputDirectory, } from "../run/contained-output.js";
+import { implicitProjectDirectoryExists, readImplicitProjectFile, validateCwd, } from "../run/project.js";
+const DOCTOR_SCHEMA = "humanish.doctor-result.v1";
+/**
+ * Version 2.3.1 stopped holding a launched background command's event stream open. Version 2.3.2
+ * also requires an e2b release whose background command handle supports sendStdin and closeStdin,
+ * which the optional speech transport needs. On older releases the CLI could stay alive minutes
+ * past a written result (#581, measured 2026-09-04 on 2.2.3: twelve minutes).
+ */
+export const DESKTOP_SDK_FLOOR = "2.3.2";
+/** The advisory `doctor` attaches to an installed desktop SDK older than the floor, else undefined. */
+export function desktopSdkAdvisory(version) {
+    if (version === undefined)
+        return undefined;
+    const parse = (value) => value
+        .split(".")
+        .slice(0, 3)
+        .map((part) => Number.parseInt(part, 10));
+    const have = parse(version);
+    const floor = parse(DESKTOP_SDK_FLOOR);
+    if (have.length < 3 || have.some((part) => !Number.isFinite(part)))
+        return undefined;
+    const older = have[0] < floor[0] ||
+        (have[0] === floor[0] &&
+            (have[1] < floor[1] || (have[1] === floor[1] && have[2] < floor[2])));
+    return older
+        ? `@e2b/desktop ${version} is older than ${DESKTOP_SDK_FLOOR}, the supported floor for background command cleanup and stdin handles (older releases could keep the CLI alive minutes past its result, #581). Update with \`npm i -D @e2b/desktop@latest\`.`
+        : undefined;
+}
+/** The version of the @e2b/desktop that `import("@e2b/desktop")` resolves to from here, if readable. */
+async function installedDesktopSdkVersion() {
+    try {
+        const { createRequire } = await import("node:module");
+        const manifest = createRequire(import.meta.url).resolve("@e2b/desktop/package.json");
+        const parsed = JSON.parse(await readFile(manifest, "utf8"));
+        return typeof parsed.version === "string" ? parsed.version : undefined;
+    }
+    catch {
+        return undefined;
+    }
+}
+export async function doctor(cwdInput, options = {}) {
+    const cwd = path.resolve(cwdInput);
+    const cwdOk = await validateCwd(cwd)
+        .then((error) => error === null)
+        .catch(() => false);
+    if (!cwdOk) {
+        const checks = uncheckedProjectChecks("this directory does not exist, or humanish cannot read it", "not checked — the target directory could not be read");
+        return { schema: DOCTOR_SCHEMA, ok: false, cwd, checks };
+    }
+    let projectRoot;
+    try {
+        projectRoot = await prepareSelectedOutputDirectory(path.dirname(cwd), cwd);
+    }
+    catch {
+        const checks = uncheckedProjectChecks("target directory failed containment validation", "not checked — containment validation failed first");
+        return { schema: DOCTOR_SCHEMA, ok: false, cwd, checks };
+    }
+    const env = options.env ?? process.env;
+    const agents = await detectLocalAgents({ ...options.localAgents, env });
+    const { probes, receivingKey } = await probeDoctorKeys(cwd, env, options.lab, options.keyDeps);
+    const setup = options.lab
+        ? await labSetupChecks({
+            cwd,
+            lab: options.lab,
+            env,
+            agents,
+            keyPresent: (name) => probes.some((probe) => probe.name === name && probe.source !== null),
+        })
+        : undefined;
+    const checks = [
+        ...(await projectChecks(projectRoot)),
+        await desktopSdkCheck(setup),
+        terminalSurfaceCheck(),
+        // The operator's own signed-in coding agent, reported as a CAPABILITY and never a gate: a
+        // machine with none is not broken, it just needs a provider key. This row exists because
+        // "go make an API key" is where most people trying humanish stop, and a developer very often
+        // already has one of these signed in.
+        { name: "local agents", ok: true, message: localAgentDoctorMessage(agents) },
+        ...keyChecks(probes, receivingKey, setup, agents),
+        ...(setup?.checks ?? [
+            {
+                name: "setup route",
+                ok: true,
+                message: "General capabilities only. Use humanish doctor --lab <lab> for the selected participant's requirements and separate analysis readiness.",
+            },
+        ]),
+    ];
+    return {
+        schema: DOCTOR_SCHEMA,
+        ok: checks.every((check) => check.ok),
+        cwd,
+        checks,
+    };
+}
+/** The rows for a target directory doctor could not open: the failure, then three unrun checks. */
+function uncheckedProjectChecks(targetMessage, reason) {
+    return [
+        { name: "target cwd", ok: false, message: targetMessage },
+        { name: "package.json", ok: false, checked: false, message: reason },
+        { name: "humanish source", ok: false, checked: false, message: reason },
+        { name: "runtime ignore", ok: false, checked: false, message: reason },
+    ];
+}
+async function safeCheck(check) {
+    try {
+        return await check();
+    }
+    catch {
+        return false;
+    }
+}
+/** The target directory, its package.json, the humanish/ source and the .humanish/ ignore rule. */
+async function projectChecks(projectRoot) {
+    return [
+        {
+            name: "target cwd",
+            ok: true,
+            message: "target directory exists",
+        },
+        await (async () => {
+            try {
+                const contents = await readImplicitProjectFile(projectRoot, "package.json");
+                return {
+                    name: "package.json",
+                    ok: true,
+                    message: contents === null
+                        ? "package.json is absent; it is optional for humanish, so npm-script integration is skipped"
+                        : "package.json is present and safe to read",
+                };
+            }
+            catch {
+                return {
+                    name: "package.json",
+                    ok: false,
+                    message: "package.json could not be safely read",
+                };
+            }
+        })(),
+        {
+            name: "humanish source",
+            ok: await safeCheck(() => implicitProjectDirectoryExists(projectRoot, "humanish")),
+            message: "committed humanish/ source directory is present and safe to read",
+        },
+        {
+            name: "runtime ignore",
+            ok: await safeCheck(async () => (await readImplicitProjectFile(projectRoot, ".gitignore"))?.includes(".humanish/") ??
+                false),
+            message: ".gitignore safely contains .humanish/",
+        },
+    ];
+}
+/**
+ * The optional peer dep every live browser and terminal lane needs (#346). `npx -y humanish` does
+ * not pull optional peers, so an adopter's FIRST live run used to fail on it — safely and at $0,
+ * but as a burned first impression on the flagship path. Answering it here means the readiness
+ * command actually answers readiness.
+ */
+async function desktopSdkCheck(setup) {
+    const present = await safeCheck(async () => {
+        try {
+            await import("@e2b/desktop");
+            return true;
+        }
+        catch {
+            return false;
+        }
+    });
+    const version = present ? await installedDesktopSdkVersion() : undefined;
+    const advisory = desktopSdkAdvisory(version);
+    return {
+        name: "e2b desktop sdk",
+        ok: present || setup?.desktop === false,
+        message: present
+            ? `optional peer @e2b/desktop ${version ?? "(version unread)"} is installed; provider access is not tested${advisory === undefined ? "" : `. ${advisory}`}`
+            : setup?.desktop === false
+                ? "optional peer @e2b/desktop is absent; not required by the selected route"
+                : "optional peer @e2b/desktop is NOT installed: dry runs work, but any live desktop participant will fail closed. Install it with `npm i -D @e2b/desktop`.",
+    };
+}
+/**
+ * The stakeholder surface (#455). Reported as capability, never as a gate: the TUI is optional,
+ * and `doctor` is itself mostly run by agents through a pipe, where a TTY requirement says
+ * nothing about whether the PROJECT is ready. So this row is always ok.
+ *
+ * WHO IS READING decides the wording, and a real first-contact study
+ * (labs/first-contact.yaml) is why. An agent evaluating humanish read
+ * "`humanish tui` is available in an interactive terminal", correctly concluded it was not in
+ * one, and dropped it — then wrote a report FOR A HUMAN that never mentioned the human
+ * surface at all. Discovery worked; handoff did not. A capability described to a reader who
+ * cannot use it has to be phrased as something to PASS ON, or it reads as "not for you" and
+ * dies there.
+ */
+function terminalSurfaceCheck() {
+    const supported = nodeSupportsTui();
+    const bundlePresent = existsSync(TUI_BUNDLE_URL);
+    return {
+        name: "terminal surface",
+        ok: true,
+        message: terminalSurfaceMessage({
+            supported,
+            bundlePresent,
+            interactive: process.stdout.isTTY === true,
+            nodeVersion: process.version,
+        }),
+    };
+}
+/** Probes the live-run keys, plus the receiving-email key a real-comms lab names. */
+async function probeDoctorKeys(cwd, env, lab, keyDeps) {
+    const keyNames = new Set(["OPENAI_API_KEY", "E2B_API_KEY", "GH_TOKEN", "CODEX_API_KEY"]);
+    let receivingKey = null;
+    if (lab) {
+        const { resolveLabManifest } = await import("../lab/discover.js");
+        const resolved = await resolveLabManifest(cwd, lab);
+        if (resolved.ok && resolved.config.comms?.email?.kind === "real") {
+            const { receivingRequiredKey } = await import("../comms/setup.js");
+            receivingKey = await receivingRequiredKey(cwd, resolved.config.comms.email.connection);
+            if (receivingKey)
+                keyNames.add(receivingKey);
+        }
+    }
+    const probes = await probeKeySources([...keyNames], {
+        cwd,
+        env,
+        ...(keyDeps === undefined ? {} : { deps: keyDeps }),
+    });
+    return { probes, receivingKey };
+}
+/**
+ * Provider-key discovery (#436): which source supplies each live-run key, through the same
+ * chain a live command resolves (env/--env-file, project overlay, vendor stores, the
+ * humanish user store). Values never appear; sources and fill commands do.
+ */
+function keyChecks(probes, receivingKey, setup, agents) {
+    return probes.map((probe) => {
+        const present = probe.source !== null;
+        const hint = probe.name === receivingKey
+            ? `provide ${probe.name} through process env or --env-file`
+            : probe.hint;
+        // GH_TOKEN is needed only for private clone subjects, so its absence is informational.
+        const required = setup
+            ? setup.keys.includes(probe.name)
+            : probe.name === "E2B_API_KEY" ||
+                (probe.name === "OPENAI_API_KEY" &&
+                    !agents.some((agent) => agent.authStatus === "authenticated"));
+        return {
+            name: `key ${probe.name}`,
+            ok: present || !required,
+            message: present
+                ? `supplied by ${probe.source}; presence only, validity not tested`
+                : required
+                    ? `missing from every source — ${hint}`
+                    : `not required for ${setup ? "the selected participant route" : "every route"}; ${hint}`,
+        };
+    });
+}

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

@@ -0,0 +1,67 @@
+import type { LocalAgentId } from "../actors/local-agent/cli.js";
+/** A coding agent that reports a signed-in account on this machine. */
+interface SignedInAgent {
+    id: LocalAgentId;
+    label: string;
+}
+export interface FirstRunEnvironment {
+    /** A sandbox to run the study in. Nothing live happens without it. */
+    hasE2bKey: boolean;
+    /**
+     * Whether `@e2b/desktop` resolves from this project. It is an OPTIONAL peer — the no-keys path
+     * does not need it — so a fresh `npx humanish` install does not have it, and a live run stops
+     * with "install this other package first". Found by running the published artifact cold, after
+     * two local runs passed because they resolved the peer from the repo's own node_modules.
+     */
+    hasDesktopSdk: boolean;
+    /**
+     * Whether humanish itself is installed in this project rather than running from an npx cache.
+     * It changes what advice is TRUE: a one-shot `npx humanish` resolves its optional peer relative
+     * to itself, so "install the peer here" cannot work — humanish has to be installed alongside it.
+     */
+    installedInProject: boolean;
+    /** A provider API key for the model. */
+    hasProviderKey: boolean;
+    /** The coding agents already signed in locally: Codex, Claude Code, or both. */
+    localAgents: readonly SignedInAgent[];
+    /** Host shape only; `doctor --lab local-browser` owns exact read-only readiness. */
+    platform?: NodeJS.Platform;
+    arch?: string;
+}
+export type FirstRunActor = "openai-computer-use" | "local-agent";
+/**
+ * Which brain the starter live lab should be written for. A machine with a signed-in coding agent
+ * and no provider key can still do a real live run; writing the lab for the credential the
+ * operator DOESN'T have is how a starter file becomes homework.
+ */
+export declare function starterActorFor(env: FirstRunEnvironment): FirstRunActor;
+/**
+ * The `localAgent` a local-agent starter lab names. Left out, the lab would default to Codex and
+ * refuse to run on a machine where only Claude Code is signed in.
+ */
+export declare function starterLocalAgentFor(env: FirstRunEnvironment): LocalAgentId | undefined;
+export interface FirstRunStep {
+    /** The exact command to run. */
+    command: string;
+    /** Why this one, in the register the rest of the CLI uses. */
+    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.
+ */
+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. */
+export declare const AGENTS_SECTION_MARKER = "<!-- humanish:agents-guide -->";
+/**
+ * What the NEXT coding agent needs to know about humanish in this project.
+ *
+ * AGENTS.md is the cross-vendor convention (agents.md) that Codex, Claude Code, Cursor and others
+ * 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: an agent acts on commands, not on prose.
+ */
+export declare function agentsSection(): string;
+export {};

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

@@ -0,0 +1,150 @@
+// What a person — or the coding agent setting humanish up for them — should do NEXT.
+//
+// WHY: `humanish init` wrote twenty files and stopped. The only lab that could actually run was a
+// $0 dry run; the two live ones were templates with `your-org/your-app` in them, so the first live
+// run a newcomer tried could not succeed no matter what credentials they had. Three independent
+// sources reached the same place — a participant in our own TUI study walked to the Start row and
+// found a placeholder URL, an adoption review concluded "the funnel is broken at the first live
+// run", and the release-gate participant said, unprompted, "validate one paid live study before
+// committing" (#505).
+//
+// The fix is not more surface. Increasingly the thing running `init` is a coding agent acting for
+// someone, and an agent reads stdout and does what it says. So init ends by naming the next
+// command — and names the one that will actually work ON THIS MACHINE, because a next step that
+// fails is worse than none.
+/**
+ * Which brain the starter live lab should be written for. A machine with a signed-in coding agent
+ * and no provider key can still do a real live run; writing the lab for the credential the
+ * operator DOESN'T have is how a starter file becomes homework.
+ */
+export function starterActorFor(env) {
+    if (!env.hasProviderKey && env.localAgents.length > 0)
+        return "local-agent";
+    return "openai-computer-use";
+}
+/** The signed-in agent a first study uses: Codex when it is signed in, else the one that is. */
+function preferredAgent(env) {
+    return env.localAgents.find((agent) => agent.id === "codex") ?? env.localAgents[0];
+}
+/**
+ * The `localAgent` a local-agent starter lab names. Left out, the lab would default to Codex and
+ * refuse to run on a machine where only Claude Code is signed in.
+ */
+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";
+/**
+ * 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.
+ */
+export function firstRunSteps(env) {
+    const steps = [
+        {
+            command: `${HUMANISH} run first-run`,
+            why: "an evidence preview: no browser or model runs, no keys, no spend",
+        },
+    ];
+    const localPlatform = (env.platform === "linux" && env.arch === "x64") ||
+        (env.platform === "darwin" && env.arch === "arm64");
+    if (localPlatform) {
+        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 --lab local-browser`,
+            why: `check the local browser lab (${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 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;
+    }
+    if (env.hasProviderKey || env.localAgents.length > 0) {
+        const brain = env.hasProviderKey
+            ? "your provider key"
+            : `${preferredAgent(env)?.label} (already signed in — no API key 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 REAL 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;
+    }
+    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 lab to actors[0].type: local-agent" +
+            localUnavailable,
+    });
+    return steps;
+}
+/** 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. */
+export const AGENTS_SECTION_MARKER = "<!-- humanish:agents-guide -->";
+/**
+ * What the NEXT coding agent needs to know about humanish in this project.
+ *
+ * AGENTS.md is the cross-vendor convention (agents.md) that Codex, Claude Code, Cursor and others
+ * 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: an agent acts on commands, not on prose.
+ */
+export function agentsSection() {
+    return [
+        "",
+        `## humanish ${AGENTS_SECTION_MARKER}`,
+        "",
+        "This project uses humanish: synthetic participants use the product and leave evidence.",
+        "",
+        "```bash",
+        "humanish doctor --lab try-live  # requirements for the selected participant and analysis",
+        "humanish lab list --json   # the labs in this project",
+        "humanish run first-run     # evidence preview only: no browser, model, keys, or spend",
+        "humanish doctor --lab 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",
+        "```",
+        "",
+        "- Labs are declared in `humanish/labs/*.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 lab 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` produces a redacted, share-safe draft.",
+        "- `humanish tui` is a HUMAN surface 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 lab 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.",
+        "",
+    ].join("\n");
+}

package/dist/cli/io.d.ts

@@ -0,0 +1,85 @@
+import { Command } from "commander";
+import { discoverProviderKeys } 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 interface CliIo {
+    writeOut(text: string): void;
+    writeErr(text: string): void;
+    setExitCode(code: number): void;
+    keyDiscovery?: typeof discoverProviderKeys;
+}
+export declare const JSON_OPTION_DESCRIPTION = "Print a machine-readable JSON response.";
+export interface LabCommandOptions {
+    count?: string | undefined;
+    cwd: string;
+    detach?: boolean | undefined;
+    dryRun?: boolean | undefined;
+    envFile?: string | undefined;
+    json?: boolean | undefined;
+    lanes?: string | undefined;
+    open?: boolean | undefined;
+    port?: string | undefined;
+    rerunFailedFrom?: string | undefined;
+    runId?: string | undefined;
+    /** #316: repo-relative path to an adopter scorer module; overrides review.scorer.ref when set. */
+    scorer?: string | undefined;
+    sims?: string | undefined;
+    expose?: boolean | undefined;
+    tunnel?: "ngrok" | undefined;
+    tunnelDomain?: string | undefined;
+    oauth?: "google" | undefined;
+    allowEmail?: string[] | undefined;
+    allowDomain?: string[] | undefined;
+    publicUrl?: string | undefined;
+    safe?: boolean | undefined;
+}
+export declare const defaultIo: CliIo;
+export declare function markInvocationEnvelopeWritten(command: Command): void;
+export declare function invocationEnvelopeAlreadyWritten(command: Command): boolean;
+export declare function applyEnvFileOption(args: {
+    command: Command;
+    cwd: string;
+    envFile?: string | undefined;
+    io: CliIo;
+    env?: NodeJS.ProcessEnv;
+    onDiscovered?: (names: string[]) => void;
+    /** False for the lab-running commands, which discover only once the lab resolves to live. */
+    discoverKeys?: boolean;
+}): Promise<boolean>;
+/**
+ * Provider-key discovery (#436): fill still-missing keys from the documented project overlay, the
+ * owning vendors' native stores, and the humanish user store. It is fill-only (an explicit
+ * --env-file or process env always wins), and each fill is announced by name and source on
+ * stderr, never by value. HUMANISH_STRICT_KEYS=1 restores env-only behavior.
+ */
+export declare function discoverCliKeys(args: {
+    io: CliIo;
+    cwd: string;
+    env?: NodeJS.ProcessEnv;
+    onDiscovered?: (names: string[]) => void;
+}): Promise<void>;
+export declare function parseLabCount(value: string | undefined, fallback: number): number | null;
+export declare function parseParticipantIds(value: string | undefined): string[];
+export declare function writeResult<T>(command: Command, io: CliIo, result: T, formatHuman: (result: T) => string): void;
+export declare function noteStudyFacts(command: Command, facts: TelemetryProperties): void;
+/** Exported for tests: the facts writeResult read off a command's result document. */
+export declare function studyFactsFor(command: Command): TelemetryProperties;
+export declare function formatRunHuman(result: RunResult): string;
+export declare function parsePositiveInteger(value: string): number | null;
+export declare function parseTimeoutMs(value: string): number | null;
+export declare function parseObserverPort(value: string): number | null;
+/** `--candidate` as the module option, absent when not given (exactOptionalPropertyTypes). */
+export declare function candidateOption(options: {
+    candidate?: string;
+    analysis?: string;
+    finding?: string;
+}): {
+    candidate?: string;
+    analysis?: string;
+    finding?: string;
+};
+export declare function collectRepeated(value: string, previous: string[]): string[];
+export declare function wantsJson(command: Command): boolean;
+export declare function automaticAnalysisEnvelope<T>(result: T): T;