humanish 0.104.3 → 0.106.0

package/dist/cli/commands/tui.d.ts

@@ -0,0 +1,32 @@
+import { Command } from "commander";
+import { checkCommsConnection } from "../../comms/setup.js";
+import { promptSecret } from "../secret-prompt.js";
+import { type TuiModule } from "../../tui/contract.js";
+import { type CliIo } from "../io.js";
+/**
+ * The pieces of the outside world the `tui` command touches. Injectable for the same reason
+ * `keyDiscovery` is: the refusals ARE the behavior worth testing, and a test cannot make a real
+ * TTY, an old Node, or a missing bundle appear.
+ */
+export interface TuiRuntime {
+    checkComms: typeof checkCommsConnection;
+    promptSecret: typeof promptSecret;
+    stdin: NodeJS.ReadStream;
+    stdout: NodeJS.WriteStream;
+    nodeVersion: string;
+    /** Injected so a test can pose as an agent session without touching the real process env. */
+    env: NodeJS.ProcessEnv;
+    /** Resolves the bundle, or null when it is not present. */
+    loadTui(bundle: URL): Promise<TuiModule | null>;
+}
+export declare const defaultTuiRuntime: TuiRuntime;
+/**
+ * The stakeholder surface (#455). Every other command is written so an agent can drive it; this one
+ * is the opposite — it takes the screen and waits for a person.
+ *
+ * That inversion is why it refuses rather than degrades. An agent that runs `humanish tui` with a
+ * piped stdout has asked for something that cannot exist, and the useful answer is a structured
+ * error naming the command that WOULD have answered the question. A TUI that quietly rendered
+ * frames into a pipe would poison a transcript with escape codes and look like a hang.
+ */
+export declare function registerTuiCommand(parent: Command, io: CliIo, runtime?: TuiRuntime): void;

package/dist/cli/commands/tui.js

@@ -0,0 +1,305 @@
+import { existsSync } from "node:fs";
+import { resolve } from "node:path";
+import { Command } from "commander";
+import { setUserKey } from "../../keys/key-resolution.js";
+import { saveCommsConnection } from "../../comms/connections.js";
+import { readCommsSetup } from "../../comms/setup.js";
+import { checkCommsConnection, configureCommsLab, } from "../../comms/setup.js";
+import { inspectCommsRecovery, recoverCommsReceiving } from "../../comms/receiving-recovery.js";
+import { resolveReceivingConnection } from "../../comms/receiving-runtime.js";
+import { promptSecret } from "../secret-prompt.js";
+import { runInit } from "../../lab/init.js";
+import { listLabManifests } from "../../lab/discover.js";
+import { reclaimRunSandboxes } from "../../run/reclaim.js";
+import { RunIndexCache, readRunIndex } from "../../run/run-index.js";
+import { readLabSummary } from "../../lab/summary.js";
+import { readProjectState } from "../../tui/project.js";
+import { createTuiObserverSession, stopRun, TUI_ACTION_SCHEMA } from "../../tui/actions.js";
+import { readRunDetail } from "../../run/detail.js";
+import { launchRun, readLaunchLogTail } from "../../tui/launch.js";
+import { TUI_MIN_NODE_MAJOR, nodeSupportsTui, TUI_BUNDLE_URL, } from "../../tui/contract.js";
+import { detectAgentSession } from "../../actors/agent-session.js";
+import { applyEnvFileOption, CLI_VERSION, JSON_OPTION_DESCRIPTION, markInvocationEnvelopeWritten, wantsJson, } from "../io.js";
+export const defaultTuiRuntime = {
+    checkComms: checkCommsConnection,
+    promptSecret,
+    stdin: process.stdin,
+    stdout: process.stdout,
+    env: process.env,
+    nodeVersion: process.version,
+    loadTui: async (bundle) => {
+        if (!existsSync(bundle))
+            return null;
+        return (await import(bundle.href));
+    },
+};
+const TUI_RESULT_SCHEMA = "humanish.tui-result.v1";
+function refuseTui(command, io, refusal) {
+    if (wantsJson(command)) {
+        io.writeOut(`${JSON.stringify(refusal, null, 2)}\n`);
+    }
+    else {
+        io.writeErr(`${refusal.error.message}\n`);
+    }
+    markInvocationEnvelopeWritten(command);
+    io.setExitCode(2);
+}
+/**
+ * The stakeholder surface (#455). Every other command is written so an agent can drive it; this one
+ * is the opposite — it takes the screen and waits for a person.
+ *
+ * That inversion is why it refuses rather than degrades. An agent that runs `humanish tui` with a
+ * piped stdout has asked for something that cannot exist, and the useful answer is a structured
+ * error naming the command that WOULD have answered the question. A TUI that quietly rendered
+ * frames into a pipe would poison a transcript with escape codes and look like a hang.
+ */
+export function registerTuiCommand(parent, io, runtime = defaultTuiRuntime) {
+    parent
+        .command("tui")
+        .description("Open the interactive terminal surface for browsing labs and runs (humans only).")
+        .summary("Human terminal for labs and runs; refuses detected agent sessions and non-TTY input/output. Agents: humanish lab list --json, humanish lab inspect <lab> --json, humanish runs --json.")
+        .option("--cwd <path>", "Target project directory.", ".")
+        .option("--env-file <path>", "Load a local env file for this terminal session and its runs without printing values.")
+        .option("--force", "Open it anyway in a session that looks like an agent's.")
+        .option("--json", JSON_OPTION_DESCRIPTION)
+        .action((options, command) => handleTui(io, runtime, options, command));
+}
+async function handleTui(io, runtime, options, command) {
+    const refusal = checkTuiSession(runtime, options.force === true);
+    if (refusal !== undefined) {
+        refuseTui(command, io, refusal);
+        return;
+    }
+    // The Ink app ships as a pre-built bundle beside the compiled CLI and is loaded ONLY here, so
+    // no agent-facing command pays its parse cost.
+    const bundle = TUI_BUNDLE_URL;
+    const loaded = await runtime.loadTui(bundle);
+    if (loaded === null) {
+        refuseTui(command, io, {
+            schema: TUI_RESULT_SCHEMA,
+            ok: false,
+            error: {
+                code: "HUMANISH_TUI_BUNDLE_MISSING",
+                message: `The terminal surface bundle is missing at ${bundle.pathname}. In a checkout, run \`pnpm build\`; in an install, this package is incomplete — please report it.`,
+            },
+        });
+        return;
+    }
+    const discoveredKeys = new Set();
+    if (!(await applyEnvFileOption({
+        command,
+        cwd: options.cwd,
+        envFile: options.envFile,
+        io,
+        env: runtime.env,
+        onDiscovered: (names) => names.forEach((name) => discoveredKeys.add(name)),
+    })))
+        return;
+    const exitCode = await runTuiSession(loaded, runtime, resolve(options.cwd), discoveredKeys);
+    // The surface owned the screen; it has already told the operator whatever there was to say.
+    markInvocationEnvelopeWritten(command);
+    io.setExitCode(exitCode);
+}
+/** The refusal for a session the surface cannot serve, or undefined when it may open. */
+function checkTuiSession(runtime, force) {
+    // An agent runner, even with a real terminal. `codex exec` allocates a PTY for the commands
+    // it runs, so the TTY check below passes and the surface used to open: a study watched an
+    // agent navigate the labs list and start a run it did not mean to start
+    // (humanish/labs/handed-a-human-surface.yaml). A TTY says a terminal exists, not that anyone is
+    // reading it. `--force` is the escape for the person who really is at this keyboard —
+    // capturing frames from inside an agent session is exactly that case.
+    const agent = force ? undefined : detectAgentSession(runtime.env);
+    if (agent !== undefined) {
+        return {
+            schema: TUI_RESULT_SCHEMA,
+            ok: false,
+            error: {
+                code: "HUMANISH_TUI_AGENT_SESSION",
+                message: `humanish tui is a surface for a person, and ${agent.marker} says this session belongs to ${agent.runner}. ` +
+                    "It renders frames of escape codes into a transcript, and its keys can start runs. " +
+                    "`humanish runs --json` lists runs, `humanish lab list --json` lists the labs in this project, " +
+                    "and `humanish lab run <lab> --json` starts one. If you are a person at this keyboard, add --force.",
+            },
+        };
+    }
+    if (runtime.stdin.isTTY !== true || runtime.stdout.isTTY !== true) {
+        return {
+            schema: TUI_RESULT_SCHEMA,
+            ok: false,
+            error: {
+                code: "HUMANISH_TUI_REQUIRES_TTY",
+                message: "humanish tui needs an interactive terminal. For scripted or agent use, `humanish runs --json` lists the same runs and `humanish lab run --json` starts one.",
+            },
+        };
+    }
+    if (!nodeSupportsTui(runtime.nodeVersion)) {
+        return {
+            schema: TUI_RESULT_SCHEMA,
+            ok: false,
+            error: {
+                code: "HUMANISH_TUI_UNSUPPORTED_NODE",
+                message: `humanish tui needs Node ${TUI_MIN_NODE_MAJOR} or newer (this is ${runtime.nodeVersion}). Every other humanish command still works on this runtime.`,
+            },
+        };
+    }
+    return undefined;
+}
+/**
+ * Mounts the surface until it exits, remounting it after each credential handoff. Resolves to the
+ * surface's exit code.
+ */
+async function runTuiSession(loaded, runtime, cwd, discoveredKeys) {
+    // Tests inject an isolated host context. Values stay behind the capability closures, never in
+    // view data.
+    const session = {
+        cwd,
+        runtime,
+        sessionEnv: runtime.env,
+        discoveredKeys,
+        runIndexCache: new RunIndexCache(),
+        observerSession: createTuiObserverSession(cwd),
+    };
+    let connectionNotice;
+    try {
+        for (;;) {
+            const outcome = await loaded.startTui({
+                ...(connectionNotice === undefined
+                    ? {}
+                    : { initialScreen: "connections", connectionNotice }),
+                cwd,
+                version: { cli: CLI_VERSION },
+                capabilities: tuiCapabilities(session),
+                stdin: runtime.stdin,
+                stdout: runtime.stdout,
+            });
+            if (typeof outcome === "number")
+                return outcome;
+            if (outcome.action !== "agentmail-key")
+                return 1;
+            connectionNotice = await storeAgentmailKey(session);
+        }
+    }
+    finally {
+        await session.observerSession.close();
+    }
+}
+/**
+ * The env for connection checks. Stored credentials are probed afresh: discovery fills must not
+ * become permanent env overrides when a person replaces a stored key during this terminal session.
+ */
+function connectionEnv(session) {
+    const env = { ...session.sessionEnv };
+    for (const name of session.discoveredKeys)
+        delete env[name];
+    return env;
+}
+function tuiCapabilities(session) {
+    const { cwd, runtime, sessionEnv, runIndexCache, observerSession } = session;
+    return {
+        comms: {
+            read: async () => ({
+                ...(await readCommsSetup(cwd, connectionEnv(session))),
+                ...(session.connectionCheck ? { authentication: session.connectionCheck } : {}),
+            }),
+            save: () => saveCommsConnection(cwd),
+            check: async () => {
+                session.connectionCheck = await runtime.checkComms({
+                    cwd,
+                    env: connectionEnv(session),
+                    online: true,
+                });
+                return session.connectionCheck;
+            },
+            labs: async () => (await listLabManifests(cwd)).labs.map((lab) => ({
+                title: lab.title ?? lab.id,
+                path: lab.path,
+            })),
+            configure: (lab, apply, planToken) => configureCommsLab({
+                cwd,
+                lab,
+                connection: "agentmail",
+                apply,
+                ...(planToken ? { planToken } : {}),
+            }),
+            recovery: () => inspectCommsRecovery({ cwd }),
+            recover: async (runId, connectionName) => {
+                try {
+                    const { connection, adapter } = await resolveReceivingConnection(cwd, connectionName, connectionEnv(session));
+                    return await recoverCommsReceiving({
+                        cwd,
+                        runId,
+                        connectionName,
+                        apiKeyEnv: connection.apiKeyEnv,
+                        adapter,
+                    });
+                }
+                catch {
+                    return {
+                        ok: false,
+                        message: "Could not recover email resources. Check the connection and retry.",
+                    };
+                }
+            },
+        },
+        // One cache for the life of the surface: it refreshes on a cadence, and re-walking every
+        // run tree each tick is the cost this index exists to avoid.
+        readRunIndex: (target, readOptions) => readRunIndex(target, { ...readOptions, cache: runIndexCache }),
+        listLabs: listLabManifests,
+        startRun: (launchOptions) => launchRun({ ...launchOptions, env: sessionEnv }),
+        readLaunchLog: readLaunchLogTail,
+        readRunDetail,
+        readLabSummary: (target, lab, readOptions) => readLabSummary(target, lab, { ...readOptions, env: sessionEnv }),
+        readProjectState,
+        openObserver: (target, observerPath) => observerSession.open(target, observerPath),
+        reclaimRun: (target, runId) => reclaimRunSandboxes(target, runId),
+        stopRun,
+        initProject: async (target) => {
+            const result = await runInit({ cwd: target, yes: true });
+            return result.ok
+                ? {
+                    schema: TUI_ACTION_SCHEMA,
+                    ok: true,
+                    message: `set up humanish here — ${result.changes.filter((change) => change.action !== "skip").length} files written`,
+                }
+                : {
+                    schema: TUI_ACTION_SCHEMA,
+                    ok: false,
+                    message: result.error?.message ?? "humanish init could not set this directory up",
+                };
+        },
+    };
+}
+/**
+ * Prompts for the AgentMail key after the surface has unmounted, stores it and checks it. Resolves
+ * to the notice the remounted connections screen shows.
+ */
+async function storeAgentmailKey(session) {
+    const { cwd, runtime, sessionEnv } = session;
+    // startTui has unmounted: only the host reads the credential, then remounts the view.
+    const value = await runtime.promptSecret("AgentMail API key", runtime.stdin, runtime.stdout);
+    if (value === null)
+        return "Key entry cancelled. Nothing was changed.";
+    try {
+        setUserKey("AGENTMAIL_API_KEY", value, sessionEnv);
+        // Refresh only a value filled implicitly by discovery; explicit env/file wins.
+        if (session.discoveredKeys.has("AGENTMAIL_API_KEY"))
+            delete sessionEnv.AGENTMAIL_API_KEY;
+        const saved = await saveCommsConnection(cwd);
+        const storedNotice = saved.ok
+            ? "Key stored. Project connection saved."
+            : `Key stored for your user. ${saved.message}`;
+        runtime.stdout.write("Checking AgentMail authentication…\n");
+        const check = await runtime.checkComms({ cwd, env: connectionEnv(session), online: true });
+        session.connectionCheck = check;
+        return saved.ok
+            ? check.authenticated === true
+                ? "Key stored. Authentication passed."
+                : check.authenticated === false
+                    ? "Key stored. Authentication rejected; test it for details."
+                    : "Key stored. Authentication unknown; test it to retry."
+            : `${storedNotice} ${check.message}`;
+    }
+    catch {
+        return "Could not store the key. Use a single non-empty line and check key-store permissions.";
+    }
+}

package/dist/cli/commands/watch.d.ts

@@ -0,0 +1,3 @@
+import { Command } from "commander";
+import { type CliIo } from "../io.js";
+export declare function registerWatchCommand(parent: Command, io: CliIo): void;

package/dist/cli/commands/watch.js

@@ -0,0 +1,245 @@
+import { Command, Option } from "commander";
+import { renderObserver, serveObserver } from "../../observer/render.js";
+import { WATCH_SAFE_NOT_APPLICABLE_MESSAGE } from "../../observer/exposure.js";
+import { runDryRun } from "../../run/dry-run.js";
+import { runLabCommand } from "./lab-run.js";
+import { applyEnvFileOption, collectRepeated, formatRunHuman, JSON_OPTION_DESCRIPTION, parseObserverPort, parsePositiveInteger, wantsJson, writeResult, } from "../io.js";
+import { followObserver, formatObserverHuman, watchExposeRequested } from "../observer-follow.js";
+export function registerWatchCommand(parent, io) {
+    parent
+        .command("watch")
+        .argument("[lab]", "Optional lab id or .yaml path to run and observe.")
+        .description("Run synthetic participants, open the observer, and keep the shell attached.")
+        .summary("Run participants, open the observer, stay attached.")
+        .option("--lab <id-or-path>", "Explicit lab id or .yaml path.")
+        .option("--run <id>", "Watch an existing run id or latest pointer.")
+        .option("--dry-run", "Lab only: render contract evidence without live provider spend.")
+        .option("--sims <count>", "Start a fresh synthetic run with this many participants before rendering. Defaults to 4 when --run is omitted.")
+        .option("--count <count>", "Lab only: override the headed desktop participant count.")
+        .option("--scorer <path>", "Terminal/computer-use/shared-world labs only: repo-relative adopter scorer module (.mjs). Overrides review.scorer.ref. Executable code: review it as code.")
+        .option("--run-id <id>", "Explicit run id for deterministic fixture tests; refused when that run already exists.")
+        .option("--cwd <path>", "Target project directory.", ".")
+        .option("--env-file <path>", "Load a local env file for this watch without persisting values.")
+        .option("--open", "Open the observer in the default browser.")
+        .option("--no-open", "Render without opening a browser.")
+        .addOption(new Option("--follow", "Deprecated; human output follows by default.").hideHelp())
+        .option("--detach", "Render/open once and exit without attached watch server.")
+        .option("--port <port>", "Local observer server port when following.", "0")
+        .option("--expose", "CUA lab only: expose the live run through an authenticated edge so you can watch from a phone. Requires edge auth.")
+        .addOption(new Option("--tunnel <provider>", "Spawn the external tunnel binary against the loopback port.").choices(["ngrok"]))
+        .option("--tunnel-domain <domain>", "Reserved domain passed to ngrok as --url (e.g. observer.example.com). Requires --tunnel.")
+        .addOption(new Option("--oauth <provider>", "Turn on ngrok edge OAuth. Requires --tunnel.").choices([
+        "google",
+    ]))
+        .option("--allow-email <addr>", "Edge OAuth allow rule: permit this email. Repeatable. Requires --oauth.", collectRepeated, [])
+        .option("--allow-domain <domain>", "Edge OAuth allow rule: permit this domain. Repeatable. Requires --oauth.", collectRepeated, [])
+        .option("--public-url <origin>", "Bring-your-own authed edge (Cloudflare Access/Tailscale/manual). Binds loopback and trusts your edge. Requires --expose.")
+        .option("--safe", "Not applicable to watch: a live run is never share_ready, so --safe (a `serve` library filter) is rejected here. Restrict viewers with edge auth (--allow-email/--allow-domain).")
+        .option("--json", JSON_OPTION_DESCRIPTION)
+        .addHelpText("after", [
+        "",
+        "Happy path:",
+        "  humanish watch",
+        "  humanish watch first-run",
+        "  humanish watch --lab .humanish/labs/local.yaml",
+        "",
+        "Watch a live CUA run from your phone (tunnel-edge auth):",
+        "  humanish watch my-cua-lab --expose --tunnel ngrok --oauth google --allow-email you@example.com",
+        "",
+        "Agent/CI path:",
+        "  humanish watch --json --no-open",
+        "",
+        "Existing evidence:",
+        "  humanish watch --run latest --detach",
+    ].join("\n"))
+        .action((labArg, options, command) => handleWatch(io, labArg, options, command));
+}
+async function handleWatch(io, labArg, options, command) {
+    const lab = options.lab ?? labArg;
+    if (options.lab !== undefined && labArg !== undefined) {
+        refuseWatch(command, io, options.cwd, {
+            code: "HUMANISH_WATCH_OPTION_CONFLICT",
+            message: "Use either positional lab or --lab, not both.",
+        });
+        return;
+    }
+    if (!(await applyEnvFileOption({
+        command,
+        cwd: options.cwd,
+        envFile: options.envFile,
+        io,
+        // runLabCommand discovers keys for a live lab; a preview or a saved run needs none.
+        discoverKeys: false,
+    }))) {
+        return;
+    }
+    if (lab) {
+        await watchLab(io, command, lab, options);
+        return;
+    }
+    // Exposure is only meaningful for a live CUA lab run (it serves the live desktop). The
+    // non-lab watch path (existing evidence, or a fresh synthetic run) has no live desktop to
+    // stream, so exposure flags there are refused rather than silently ignored — use `serve`.
+    if (watchExposeRequested(options)) {
+        refuseWatch(command, io, options.cwd, {
+            code: "HUMANISH_WATCH_OPTION_CONFLICT",
+            message: "--expose/--tunnel/--oauth apply only to a live CUA lab run; to expose finished evidence use `humanish serve --expose`.",
+        });
+        return;
+    }
+    // --safe is a `serve` library filter; watch shows one run and has nothing it could filter.
+    if (options.safe === true) {
+        refuseWatch(command, io, options.cwd, {
+            code: "HUMANISH_WATCH_SAFE_NOT_APPLICABLE",
+            message: WATCH_SAFE_NOT_APPLICABLE_MESSAGE,
+        });
+        return;
+    }
+    const target = resolveWatchTarget(options, command);
+    if ("code" in target) {
+        refuseWatch(command, io, options.cwd, target);
+        return;
+    }
+    const wantsMachine = wantsJson(command);
+    const shouldOpen = options.open === false
+        ? false
+        : options.open === true
+            ? true
+            : !wantsMachine && process.stdout.isTTY === true;
+    const wantsFollow = !wantsMachine && options.detach !== true && options.follow !== false;
+    const staticOpen = wantsFollow ? false : shouldOpen;
+    const rendered = await renderWatchEvidence(io, command, options, target.requestedParticipantCount, staticOpen);
+    if (rendered === undefined)
+        return;
+    await reportWatch(io, command, rendered, {
+        follow: wantsFollow,
+        open: shouldOpen,
+        port: target.port,
+    });
+}
+function refuseWatch(command, io, cwd, refusal) {
+    const result = {
+        schema: "humanish.run-result.v1",
+        ok: false,
+        cwd,
+        warnings: [],
+        error: refusal,
+    };
+    writeResult(command, io, result, formatRunHuman);
+    io.setExitCode(2);
+}
+/** A lab argument starts that lab under watch; `--run` would name other evidence. */
+async function watchLab(io, command, lab, options) {
+    if (options.run !== undefined) {
+        refuseWatch(command, io, options.cwd, {
+            code: "HUMANISH_WATCH_OPTION_CONFLICT",
+            message: "Use either a lab to start evidence or --run to watch existing evidence, not both.",
+        });
+        return;
+    }
+    await runLabCommand({
+        command,
+        io,
+        lab,
+        mode: "watch",
+        options: {
+            cwd: options.cwd,
+            ...(options.count === undefined ? {} : { count: options.count }),
+            ...(options.detach === undefined ? {} : { detach: options.detach }),
+            ...(options.dryRun === undefined ? {} : { dryRun: options.dryRun }),
+            ...(options.open === undefined ? {} : { open: options.open }),
+            port: options.port,
+            ...(options.runId === undefined ? {} : { runId: options.runId }),
+            ...(options.scorer === undefined ? {} : { scorer: options.scorer }),
+            ...(options.sims === undefined ? {} : { sims: options.sims }),
+            ...(options.expose === undefined ? {} : { expose: options.expose }),
+            ...(options.tunnel === undefined ? {} : { tunnel: options.tunnel }),
+            ...(options.tunnelDomain === undefined ? {} : { tunnelDomain: options.tunnelDomain }),
+            ...(options.oauth === undefined ? {} : { oauth: options.oauth }),
+            allowEmail: options.allowEmail,
+            allowDomain: options.allowDomain,
+            ...(options.publicUrl === undefined ? {} : { publicUrl: options.publicUrl }),
+            ...(options.safe === undefined ? {} : { safe: options.safe }),
+            ...(options.json === undefined ? {} : { json: options.json }),
+        },
+    });
+}
+/** Without a lab, watch shows existing evidence (`--run`) or a fresh synthetic run (`--sims`). */
+function resolveWatchTarget(options, command) {
+    const runOptionSource = typeof command.getOptionValueSource === "function"
+        ? command.getOptionValueSource("run")
+        : undefined;
+    const runWasOmitted = runOptionSource === undefined || runOptionSource === "default";
+    const participantCount = options.sims === undefined ? undefined : parsePositiveInteger(options.sims);
+    const port = parseObserverPort(options.port);
+    if (options.sims !== undefined && participantCount === null) {
+        return { code: "HUMANISH_INVALID_SIM_COUNT", message: "--sims must be a positive integer." };
+    }
+    if (!runWasOmitted && options.sims !== undefined) {
+        return {
+            code: "HUMANISH_WATCH_OPTION_CONFLICT",
+            message: "Use either --run to watch existing evidence or --sims to start a fresh run, not both.",
+        };
+    }
+    if (!runWasOmitted && options.runId !== undefined) {
+        return {
+            code: "HUMANISH_WATCH_OPTION_CONFLICT",
+            message: "--run-id only applies to fresh watch runs; remove --run or remove --run-id.",
+        };
+    }
+    if (port === null) {
+        return {
+            code: "HUMANISH_INVALID_PORT",
+            message: "--port must be an integer between 0 and 65535.",
+        };
+    }
+    return { requestedParticipantCount: participantCount ?? (runWasOmitted ? 4 : undefined), port };
+}
+/** Render the evidence to show; undefined when a fresh run failed and its result was written. */
+async function renderWatchEvidence(io, command, options, requestedParticipantCount, staticOpen) {
+    if (requestedParticipantCount !== undefined && requestedParticipantCount !== null) {
+        // A fresh run renders through its finished run, so the page shown is the run just
+        // written, never a directory swapped in under its id.
+        const runResult = await runDryRun({
+            cwd: options.cwd,
+            dryRun: true,
+            simCount: requestedParticipantCount,
+            ...(options.runId === undefined ? {} : { runId: options.runId }),
+            observer: { open: staticOpen },
+        });
+        if (!runResult.ok || runResult.observer === undefined) {
+            writeResult(command, io, runResult, formatRunHuman);
+            io.setExitCode(2);
+            return undefined;
+        }
+        return runResult.observer;
+    }
+    return renderObserver(options.cwd, options.run ?? "latest", {
+        open: staticOpen,
+    });
+}
+/** Write the result, then keep a live server attached when following. */
+async function reportWatch(io, command, rendered, serve) {
+    let server = null;
+    let result = rendered;
+    if (rendered.ok && serve.follow) {
+        server = await serveObserver(rendered, { open: serve.open, port: serve.port });
+        result = {
+            ...rendered,
+            observerUrl: server.url,
+            serverUrl: server.url,
+            opened: server.opened,
+            ...(server.openCommand ? { openCommand: server.openCommand } : {}),
+            warnings: [
+                ...rendered.warnings,
+                "Live observer server is polling observer-data.json with no-store caching.",
+                ...(server.warning ? [server.warning] : []),
+            ],
+        };
+    }
+    writeResult(command, io, result, formatObserverHuman);
+    io.setExitCode(result.ok ? 0 : 2);
+    if (result.ok && server) {
+        await followObserver(io, result, server);
+    }
+}

package/dist/cli/doctor.d.ts

@@ -0,0 +1,39 @@
+import { type KeyResolutionDeps } from "../keys/key-resolution.js";
+import { type DetectLocalAgentsOptions } from "../actors/local-agent/cli.js";
+declare const DOCTOR_SCHEMA = "humanish.doctor-result.v1";
+export interface DoctorResult {
+    schema: typeof DOCTOR_SCHEMA;
+    ok: boolean;
+    cwd: string;
+    checks: Array<{
+        name: string;
+        ok: boolean;
+        message: string;
+        /**
+         * ADDITIVE + OPTIONAL. `false` means the check never ran — the directory could not be read, so
+         * there is nothing to report about it either way. Absent means it ran and `ok` is its verdict.
+         *
+         * It exists because a failed check and an unrun one used to render identically, and the unrun
+         * rows carried the SUCCESS text: a participant read `missing package.json: package.json is
+         * present and safe to read` off a real screen (labs/tui-self-study.yaml).
+         */
+        checked?: boolean;
+    }>;
+}
+/**
+ * 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 declare const DESKTOP_SDK_FLOOR = "2.3.2";
+/** The advisory `doctor` attaches to an installed desktop SDK older than the floor, else undefined. */
+export declare function desktopSdkAdvisory(version: string | undefined): string | undefined;
+export declare function doctor(cwdInput: string, options?: {
+    lab?: string;
+    env?: NodeJS.ProcessEnv;
+    localAgents?: DetectLocalAgentsOptions;
+    /** Where the key probe looks for vendor stores; tests point it at a temp home. */
+    keyDeps?: KeyResolutionDeps;
+}): Promise<DoctorResult>;
+export {};