humanish 0.104.3 → 0.106.0

package/dist/cli/commands/runs.js

@@ -0,0 +1,314 @@
+import { Command, Option } from "commander";
+import { computeStats, formatStatsHuman } from "../../run/stats.js";
+import { DEFAULT_EXPORT_MAX_BYTES, exportRun, formatExportHuman } from "../../feedback/export.js";
+import { cleanupRun, listRuns, readReview } from "../../run/stored-runs.js";
+import { runDryRun } from "../../run/dry-run.js";
+import { verifyRun } from "../../verify/verify.js";
+import { reclaimPreflightSandboxes, reclaimRunSandboxes, } from "../../run/reclaim.js";
+import { runLabCommand } from "./lab-run.js";
+import { applyEnvFileOption, formatRunHuman, JSON_OPTION_DESCRIPTION, parsePositiveInteger, writeResult, } from "../io.js";
+const SCRIPTED_BROWSER_DOCS_URL = "https://humanish.dev/docs/lab-manifests#scripted-browser-scenarios";
+export function registerRunCommand(parent, io) {
+    parent
+        .command("run")
+        .argument("[lab]", "Optional lab id or .yaml path.")
+        .description("Run a lab (or a synthetic dry-run bundle). The everyday command.")
+        .summary("Run a persona/scenario simulation or dry-run bundle.")
+        .option("--dry-run", "Generate contract proof without browser, keys, or provider spend.")
+        // `humanish run <lab>` and `humanish lab run <lab>` are the SAME operation on the same
+        // dispatcher, but this one used to forward four options while its sibling forwarded all of
+        // them — so `humanish run first-run --no-open` failed while `lab run` accepted it. A
+        // participant hit exactly that and filed it as a documentation mismatch. Same command, same
+        // flags (CLIG: "be consistent across subcommands").
+        .option("--open", "Open the observer in the default browser.")
+        .option("--no-open", "Render without opening a browser.")
+        .option("--detach", "Render/open once and exit without an attached watch server.")
+        .option("--port <port>", "Local observer server port when following.", "0")
+        .option("--sims <count>", "Simulation count. A dry run accepts any positive count.")
+        // Agents with an older installed skill still send --app-url. Accepting it hidden lets the
+        // refusal name the replacement; commander's bare unknown-option error names nothing. Delete
+        // after 0.106.x.
+        .addOption(new Option("--app-url <url>").hideHelp())
+        .option("--cwd <path>", "Target project directory.", ".")
+        .option("--env-file <path>", "Load a local env file for this run without persisting values.")
+        .option("--run-id <id>", "Explicit run id for deterministic fixture tests; refused when that run already exists.")
+        .option("--json", JSON_OPTION_DESCRIPTION)
+        .action(async (lab, options, command) => {
+        if (options.appUrl !== undefined) {
+            const result = {
+                schema: "humanish.run-result.v1",
+                ok: false,
+                cwd: options.cwd,
+                warnings: [],
+                error: {
+                    code: "HUMANISH_APP_URL_REMOVED",
+                    message: `--app-url was removed. To drive an app on a loopback URL, write a scripted-browser lab and run \`humanish run <lab>\`: ${SCRIPTED_BROWSER_DOCS_URL}`,
+                },
+            };
+            writeResult(command, io, result, formatRunHuman);
+            io.setExitCode(2);
+            return;
+        }
+        if (!(await applyEnvFileOption({
+            command,
+            cwd: options.cwd,
+            envFile: options.envFile,
+            io,
+            // runLabCommand discovers keys for a live lab; the lab-less preview needs none.
+            discoverKeys: false,
+        }))) {
+            return;
+        }
+        if (lab) {
+            await runLabCommand({
+                command,
+                io,
+                lab,
+                mode: "run",
+                // Forwarded wholesale, exactly as `lab run` does. Cherry-picking a subset here is what
+                // made the two commands disagree in the first place.
+                options: options,
+            });
+            return;
+        }
+        const participantCount = options.sims === undefined ? undefined : parsePositiveInteger(options.sims);
+        if (options.sims !== undefined && participantCount === null) {
+            const result = {
+                schema: "humanish.run-result.v1",
+                ok: false,
+                cwd: options.cwd,
+                warnings: [],
+                error: {
+                    code: "HUMANISH_INVALID_SIM_COUNT",
+                    message: "--sims must be a positive integer.",
+                },
+            };
+            writeResult(command, io, result, formatRunHuman);
+            io.setExitCode(2);
+            return;
+        }
+        const result = await runDryRun({
+            cwd: options.cwd,
+            ...(options.dryRun === undefined ? {} : { dryRun: options.dryRun }),
+            ...(options.runId === undefined ? {} : { runId: options.runId }),
+            ...(participantCount === undefined || participantCount === null
+                ? {}
+                : { simCount: participantCount }),
+            // Rendered the way `watch` renders it, so a bundle is the same bundle whichever command
+            // produced it (#597). A render failure is a warning on the result.
+            observer: { open: false },
+        });
+        writeResult(command, io, result, formatRunHuman);
+        io.setExitCode(result.ok ? 0 : 2);
+    });
+}
+export function registerVerifyCommand(parent, io) {
+    parent
+        .command("verify")
+        .description("Validate a run bundle and public-safety gates.")
+        .summary("Validate a run bundle and public-safety gates.")
+        .option("--run <id>", "Run id or latest pointer.", "latest")
+        .option("--cwd <path>", "Target project directory.", ".")
+        .option("--json", JSON_OPTION_DESCRIPTION)
+        .action(async (options, command) => {
+        const result = await verifyRun(options.cwd, options.run);
+        writeResult(command, io, result, formatVerifyHuman);
+        io.setExitCode(result.ok ? 0 : 2);
+    });
+}
+export function registerCleanupCommand(parent, io) {
+    parent
+        .command("cleanup")
+        .description("Inspect recorded resource evidence and write cleanup.json; stored ids do not authorize provider mutation.")
+        .summary("Write a resource cleanup inspection receipt.")
+        .option("--run <id>", "Run id or latest pointer.", "latest")
+        .option("--cwd <path>", "Target project directory.", ".")
+        .option("--json", JSON_OPTION_DESCRIPTION)
+        .action(async (options, command) => {
+        const result = await cleanupRun(options.cwd, options.run);
+        writeResult(command, io, result, formatCleanupHuman);
+        io.setExitCode(result.ok ? 0 : 2);
+    });
+}
+export function registerReviewCommand(parent, io) {
+    parent
+        .command("review")
+        .description("Build a review packet from verified run evidence.")
+        .summary("Build a review packet from verified run evidence.")
+        .option("--run <id>", "Run id or latest pointer.", "latest")
+        .option("--cwd <path>", "Target project directory.", ".")
+        .option("--json", JSON_OPTION_DESCRIPTION)
+        .action(async (options, command) => {
+        const result = await readReview(options.cwd, options.run);
+        writeResult(command, io, result, (value) => `${JSON.stringify(value, null, 2)}\n`);
+        io.setExitCode("ok" in result && result.ok === false ? 2 : 0);
+    });
+}
+export function registerExportCommand(parent, io) {
+    parent
+        .command("export")
+        .description("Export a run as self-contained Observer HTML, or a separately verified redacted bundle workspace. HTML requires share_ready unless --local-only; bundle format requires --redact-screenshots and preserves the original.")
+        .summary("Export Observer HTML or a redacted bundle workspace.")
+        .option("--run <id>", "Run id or 'latest'.", "latest")
+        .addOption(new Option("--format <format>", "Output format; bundle creates a new standalone workspace.")
+        .choices(["html", "bundle"])
+        .default("html"))
+        .option("--redact-screenshots", "Bundle only: blur PNG screenshots in a verified copy; keep original evidence unchanged.")
+        .option("--out <path>", "HTML file or new bundle workspace. Default: .humanish/exports/<runId>.html or <runId>-redacted/.")
+        .option("--local-only", "Export a bundle that is not share_ready, with a LOCAL ONLY banner in the file.")
+        .option("--max-bytes <n>", "Refuse an export larger than this.", String(DEFAULT_EXPORT_MAX_BYTES))
+        .option("--cwd <path>", "Target project directory.", ".")
+        .option("--json", JSON_OPTION_DESCRIPTION)
+        .action(async (options, command) => {
+        const maxBytes = options.format === "bundle"
+            ? Number(options.maxBytes)
+            : Number.parseInt(options.maxBytes, 10);
+        const result = await exportRun(options.cwd, options.run, {
+            format: options.format,
+            ...(options.redactScreenshots === undefined
+                ? {}
+                : { redactScreenshots: options.redactScreenshots }),
+            ...(options.out === undefined ? {} : { out: options.out }),
+            ...(options.localOnly === undefined ? {} : { localOnly: options.localOnly }),
+            ...(options.format === "bundle" || (Number.isFinite(maxBytes) && maxBytes > 0)
+                ? { maxBytes }
+                : {}),
+        });
+        writeResult(command, io, result, formatExportHuman);
+        io.setExitCode(result.ok ? 0 : 2);
+    });
+}
+export function registerStatsCommand(parent, io) {
+    parent
+        .command("stats")
+        .description("Cost, outcome, and duration roll-ups across run history. Estimates stay labelled; unknown costs count as unknown.")
+        .summary("Roll up cost, outcomes, and durations across runs.")
+        .option("--lab <id>", "Only runs from this lab id.")
+        .option("--since <date>", "Only runs that started on or after this ISO date or datetime.")
+        .option("--cwd <path>", "Target project directory.", ".")
+        .option("--json", JSON_OPTION_DESCRIPTION)
+        .action(async (options, command) => {
+        const result = await computeStats(options.cwd, {
+            ...(options.lab === undefined ? {} : { lab: options.lab }),
+            ...(options.since === undefined ? {} : { since: options.since }),
+        });
+        writeResult(command, io, result, formatStatsHuman);
+        io.setExitCode(result.ok ? 0 : 2);
+    });
+}
+export function registerRunsCommand(parent, io) {
+    parent
+        .command("runs")
+        .description("List local humanish runs and latest pointers.")
+        .summary("List local humanish runs and latest pointers.")
+        .option("--cwd <path>", "Target project directory.", ".")
+        .option("--json", JSON_OPTION_DESCRIPTION)
+        .action(async (options, command) => {
+        const result = await listRuns(options.cwd);
+        writeResult(command, io, result, formatRunsHuman);
+        io.setExitCode(result.ok ? 0 : 2);
+    });
+}
+export function registerRuntimeCommands(parent, io) {
+    const runtime = parent
+        .command("runtime")
+        .description("Prepare or inspect the local browser runtime.");
+    for (const action of ["status", "setup"]) {
+        runtime
+            .command(action)
+            .description(action === "status"
+            ? "Check local Docker, virtualization and the cached browser image without downloads."
+            : "Download and install the local browser image. Does not start a study or use model quota.")
+            .option("--json", JSON_OPTION_DESCRIPTION)
+            .option("--media", "Prepare or inspect the optional camera and speech runtime.")
+            .action(async (_options, command) => {
+            const { localRuntimeStatus, prepareLocalRuntime } = await import("../../substrates/local/runtime.js");
+            try {
+                if (action === "setup")
+                    await prepareLocalRuntime({
+                        media: _options.media === true,
+                        progress: (message) => io.writeErr(`${message}\n`),
+                    });
+                const status = await localRuntimeStatus({ media: _options.media === true });
+                const result = { schema: "humanish.runtime-result.v1", ...status };
+                writeResult(command, io, result, () => `${status.message}\n`);
+                io.setExitCode(status.ok ? 0 : 2);
+            }
+            catch (error) {
+                const message = error instanceof Error
+                    ? error.message
+                    : "Local runtime setup failed. Run humanish runtime setup to retry.";
+                const result = {
+                    schema: "humanish.runtime-result.v1",
+                    ok: false,
+                    error: { code: "HUMANISH_LOCAL_RUNTIME_SETUP_FAILED", message },
+                };
+                writeResult(command, io, result, () => `${message}\n`);
+                io.setExitCode(2);
+            }
+        });
+    }
+}
+export function registerReclaimCommand(parent, io) {
+    parent
+        .command("reclaim")
+        .description("Kill an interrupted run's sandboxes by the exact ids journaled in its sandbox-receipts.ndjson; never enumerates the E2B account. Needs E2B_API_KEY in the environment.")
+        .summary("Reclaim an interrupted run's sandboxes by recorded id.")
+        .option("--cwd <path>", "Target project directory.", ".")
+        .option("--run <id>", "Run id, or 'latest'.", "latest")
+        .addOption(new Option("--preflight", "Reclaim sandboxes left by interrupted `humanish lab preflight` probes (journaled in .humanish/preflight) instead of a run's.").conflicts("run"))
+        .option("--json", JSON_OPTION_DESCRIPTION)
+        .action(async (options, command) => {
+        const result = options.preflight
+            ? await reclaimPreflightSandboxes(options.cwd)
+            : await reclaimRunSandboxes(options.cwd, options.run);
+        writeResult(command, io, result, formatReclaimHuman);
+        io.setExitCode(result.ok ? 0 : 2);
+    });
+}
+function formatReclaimHuman(result) {
+    const lines = [];
+    lines.push(`Reclaim ${result.runId}: ${result.ok ? "ok" : "FAILED"} — ${result.receiptCount} sandbox receipt(s).`);
+    for (const outcome of result.outcomes) {
+        lines.push(`  ${outcome.sandboxId} (${outcome.laneId}): ${outcome.state}${outcome.detail ? ` — ${outcome.detail}` : ""}`);
+    }
+    for (const warning of result.warnings)
+        lines.push(`  warning: ${warning}`);
+    if (result.error)
+        lines.push(`  error: ${result.error.message}`);
+    return lines.join("\n");
+}
+function formatVerifyHuman(result) {
+    return ([
+        `humanish verify ${result.ok ? "passed" : "failed"}`,
+        `run: ${result.run}`,
+        `share-safety: ${result.shareSafety.status}`,
+        ...result.shareSafety.reasons.map((reason) => `share-safety reason: ${reason.code}: ${reason.message}`),
+        ...result.checks.map((check) => `- ${check.ok ? "ok" : "fail"} ${check.name}: ${check.message}`),
+        ...result.warnings.map((warning) => `warning: ${warning}`),
+    ].join("\n") + "\n");
+}
+function formatCleanupHuman(result) {
+    if (!result.ok && result.error) {
+        return `${result.error.code}: ${result.error.message}\n`;
+    }
+    return ([
+        `humanish cleanup ${result.ok ? "passed" : "failed"}`,
+        `run: ${result.runId ?? result.run}`,
+        `resources: already-clean ${result.summary.alreadyClean}, skipped ${result.summary.skipped}, failed ${result.summary.failed}`,
+        ...(result.cleanupPath ? [`cleanup: ${result.cleanupPath}`] : []),
+        ...result.warnings.map((warning) => `warning: ${warning}`),
+    ].join("\n") + "\n");
+}
+function formatRunsHuman(result) {
+    if (!result.ok) {
+        return `${result.error?.code}: ${result.error?.message}\n`;
+    }
+    if (result.runs.length === 0) {
+        return `No humanish runs found in ${result.cwd}\n`;
+    }
+    return ([
+        `latest: ${result.latest ?? "none"}`,
+        ...result.runs.map((run) => `- ${run.runId} ${run.mode ?? "unknown"} ${run.createdAt ?? "unknown"} ${run.path}`),
+    ].join("\n") + "\n");
+}

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

@@ -0,0 +1,11 @@
+import { Command } from "commander";
+import { type CliIo } from "../io.js";
+export declare function registerInitCommand(parent: Command, io: CliIo): void;
+export declare function registerDoctorCommand(parent: Command, io: CliIo): void;
+/**
+ * `humanish telemetry status|enable|disable` — the opt-out the convention requires, plus a `status`
+ * that prints the exact document that would be sent. "You can read what we collect" is what makes
+ * default-on honest rather than merely lawful.
+ */
+export declare function registerTelemetryCommand(parent: Command, io: CliIo): void;
+export declare function registerKeysCommand(parent: Command, io: CliIo): void;

package/dist/cli/commands/setup.js

@@ -0,0 +1,325 @@
+import { Command } from "commander";
+import { listUserKeys, resolveKeyName, setUserKey, unsetUserKey, userKeyStorePath, } from "../../keys/key-resolution.js";
+import { promptSecret } from "../secret-prompt.js";
+import { runInit } from "../../lab/init.js";
+import { buildPayload, disabledByEnvironment, readTelemetryState, telemetryStatePath, writeTelemetryState, } from "../telemetry.js";
+import { doctor } from "../doctor.js";
+import { applyEnvFileOption, CLI_VERSION, JSON_OPTION_DESCRIPTION, markInvocationEnvelopeWritten, wantsJson, writeResult, } from "../io.js";
+export function registerInitCommand(parent, io) {
+    parent
+        .command("init")
+        .description("Set up committed humanish/ source files and ignored .humanish/ runtime state.")
+        .summary("Set up humanish/ source and .humanish/ runtime state.")
+        .option("--dry-run", "Print planned changes without writing files.")
+        .option("--yes", "Apply safe generated changes without prompting.")
+        .option("--local-browser <url>", "Set the local-browser starter to this loopback app URL (explicit port above 1023).")
+        .option("--local-mission <text>", "Set the local-browser participant mission.")
+        .option("--cwd <path>", "Target project directory.", ".")
+        .option("--json", JSON_OPTION_DESCRIPTION)
+        .action(async (options, command) => {
+        const initOptions = {
+            cwd: options.cwd,
+            ...(options.dryRun === undefined ? {} : { dryRun: options.dryRun }),
+            ...(options.yes === undefined ? {} : { yes: options.yes }),
+            ...(options.localBrowser === undefined && options.localMission === undefined
+                ? {}
+                : {
+                    localBrowser: {
+                        appUrl: options.localBrowser ?? "http://127.0.0.1:3000",
+                        ...(options.localMission === undefined ? {} : { mission: options.localMission }),
+                    },
+                }),
+        };
+        const result = await runInit(initOptions);
+        if (wantsJson(command)) {
+            io.writeOut(`${JSON.stringify(result, null, 2)}\n`);
+        }
+        else if (result.ok) {
+            io.writeOut(formatInitHuman(result));
+        }
+        else {
+            io.writeErr(formatInitHuman(result));
+        }
+        io.setExitCode(result.ok ? 0 : 2);
+    });
+}
+export function registerDoctorCommand(parent, io) {
+    parent
+        .command("doctor")
+        .description("Explain project readiness and missing humanish setup.")
+        .summary("Explain project readiness and missing setup.")
+        .option("--cwd <path>", "Target project directory.", ".")
+        .option("--lab <lab>", "Check the selected lab's desktop, participant authentication and separate analysis requirements; no provider calls.")
+        .option("--env-file <path>", "Load a local env file for these setup checks without printing values.")
+        .option("--json", JSON_OPTION_DESCRIPTION)
+        .action(async (options, command) => {
+        if (options.envFile &&
+            !(await applyEnvFileOption({ command, cwd: options.cwd, envFile: options.envFile, io })))
+            return;
+        const result = await doctor(options.cwd, options.lab ? { lab: options.lab } : {});
+        writeResult(command, io, result, formatDoctorHuman);
+        // Behavioral change: was exit 1, every other structured command uses 2.
+        io.setExitCode(result.ok ? 0 : 2);
+    });
+}
+/**
+ * `humanish telemetry status|enable|disable` — the opt-out the convention requires, plus a `status`
+ * that prints the exact document that would be sent. "You can read what we collect" is what makes
+ * default-on honest rather than merely lawful.
+ */
+export function registerTelemetryCommand(parent, io) {
+    const telemetry = parent
+        .command("telemetry")
+        .description("Show or change anonymous usage collection.");
+    telemetry
+        .command("status", { isDefault: true })
+        .description("What is collected, and whether it is on.")
+        .option("--json", JSON_OPTION_DESCRIPTION)
+        .action(async (options, command) => {
+        const state = await readTelemetryState();
+        const envOff = disabledByEnvironment(process.env);
+        const sample = buildPayload({
+            event: "cli_command",
+            anonymousId: state.anonymousId,
+            version: CLI_VERSION,
+            properties: {
+                command: "lab run",
+                lab: "try-live",
+                mode: "live",
+                outcome: "incomplete",
+                brain: "provider-key",
+                durationBucket: "1-5m",
+                ok: false,
+                diagnosticCategory: "session_interrupted",
+                stopCause: "spend_limit",
+            },
+        });
+        const result = {
+            schema: "humanish.telemetry-status.v1",
+            ok: true,
+            enabled: state.enabled && !envOff,
+            disabledBy: envOff ? "environment" : state.enabled ? undefined : "config",
+            statePath: telemetryStatePath(),
+            example: sample,
+        };
+        if (options.json === true || wantsJson(command)) {
+            io.writeOut(`${JSON.stringify(result, null, 2)}\n`);
+        }
+        else {
+            io.writeOut([
+                `telemetry: ${result.enabled ? "on" : "off"}${envOff ? " (DO_NOT_TRACK / HUMANISH_TELEMETRY_DISABLED)" : ""}`,
+                `state: ${result.statePath}`,
+                "",
+                "a complete example of what is sent — there are no other fields:",
+                JSON.stringify(sample, null, 2),
+                "",
+                "never sent: labs you wrote, subjects, personas, missions, paths, run evidence, key names or values.",
+                "",
+                "humanish telemetry disable   turns it off",
+            ].join("\n") + "\n");
+        }
+        markInvocationEnvelopeWritten(command);
+    });
+    for (const [name, enabled] of [
+        ["enable", true],
+        ["disable", false],
+    ]) {
+        telemetry
+            .command(name)
+            .description(`Turn anonymous usage collection ${name === "enable" ? "on" : "off"}.`)
+            .action(async (_options, command) => {
+            const state = await readTelemetryState();
+            // Writing `noticed` here too: someone who has just made an explicit choice does not need
+            // to be told about the choice next time.
+            await writeTelemetryState({ ...state, enabled, noticed: true });
+            io.writeOut(`telemetry ${enabled ? "enabled" : "disabled"}\n`);
+            markInvocationEnvelopeWritten(command);
+        });
+    }
+}
+const KEYS_RESULT_SCHEMA = "humanish.keys-result.v1";
+function formatKeysHuman(result) {
+    const lines = [
+        `humanish keys ${result.ok ? "ok" : "failed"}`,
+        `store: ${result.store}`,
+        result.message,
+    ];
+    if (result.action === "list" && result.names.length > 0) {
+        for (const name of result.names)
+            lines.push(`- ${name}`);
+    }
+    return `${lines.join("\n")}\n`;
+}
+/** Read one secret line: from a piped stdin when --stdin, else a hidden TTY prompt. */
+async function readSecretValue(useStdin, promptLabel) {
+    if (useStdin || !process.stdin.isTTY) {
+        const chunks = [];
+        for await (const chunk of process.stdin)
+            chunks.push(chunk);
+        const text = Buffer.concat(chunks).toString("utf8").trim();
+        return text.length > 0 ? text : null;
+    }
+    return promptSecret(promptLabel, process.stdin, process.stderr);
+}
+export function registerKeysCommand(parent, io) {
+    const keys = parent
+        .command("keys")
+        .description("Manage the humanish user-level key store used by provider-key discovery.")
+        .summary("Manage the user-level provider key store.");
+    keys
+        .command("set")
+        .argument("<vendor-or-name>", "A vendor alias (openai, e2b, anthropic, github, agentmail) or a raw ENV_NAME.")
+        .description("Store one provider key in the user store (0600), prompted with hidden input.")
+        .option("--stdin", "Read the value from stdin instead of prompting (for agents/pipes).")
+        .option("--json", JSON_OPTION_DESCRIPTION)
+        .action(async (vendorOrName, options, command) => {
+        const name = resolveKeyName(vendorOrName);
+        const storePath = userKeyStorePath(process.env);
+        if (name === null) {
+            const result = {
+                schema: KEYS_RESULT_SCHEMA,
+                ok: false,
+                action: "set",
+                store: storePath,
+                names: [],
+                message: `Not a vendor alias or valid env name: ${vendorOrName}. Vendors: openai, e2b, anthropic, github, agentmail.`,
+            };
+            writeResult(command, io, result, formatKeysHuman);
+            io.setExitCode(2);
+            return;
+        }
+        const value = await readSecretValue(options.stdin === true, `Value for ${name}`);
+        if (value === null) {
+            const result = {
+                schema: KEYS_RESULT_SCHEMA,
+                ok: false,
+                action: "set",
+                store: storePath,
+                names: [name],
+                message: "No value provided; nothing written.",
+            };
+            writeResult(command, io, result, formatKeysHuman);
+            io.setExitCode(2);
+            return;
+        }
+        try {
+            const written = setUserKey(name, value, process.env);
+            const result = {
+                schema: KEYS_RESULT_SCHEMA,
+                ok: true,
+                action: "set",
+                store: written.path,
+                names: [name],
+                message: `${name} stored (0600). Live commands resolve it automatically; remove with "humanish keys unset ${name}".`,
+            };
+            writeResult(command, io, result, formatKeysHuman);
+            io.setExitCode(0);
+        }
+        catch (error) {
+            const result = {
+                schema: KEYS_RESULT_SCHEMA,
+                ok: false,
+                action: "set",
+                store: storePath,
+                names: [name],
+                message: error instanceof Error ? error.message : "Failed to write the key store.",
+            };
+            writeResult(command, io, result, formatKeysHuman);
+            io.setExitCode(2);
+        }
+    });
+    keys
+        .command("unset")
+        .argument("<vendor-or-name>", "A vendor alias or raw ENV_NAME to remove from the store.")
+        .description("Remove one key from the user store.")
+        .option("--json", JSON_OPTION_DESCRIPTION)
+        .action(async (vendorOrName, _options, command) => {
+        const name = resolveKeyName(vendorOrName);
+        const storePath = userKeyStorePath(process.env);
+        const had = name !== null && unsetUserKey(name, process.env);
+        const result = {
+            schema: KEYS_RESULT_SCHEMA,
+            ok: name !== null,
+            action: "unset",
+            store: storePath,
+            names: name === null ? [] : [name],
+            message: name === null
+                ? `Not a vendor alias or valid env name: ${vendorOrName}.`
+                : had
+                    ? `${name} removed from the store.`
+                    : `${name} was not in the store; nothing changed.`,
+        };
+        writeResult(command, io, result, formatKeysHuman);
+        io.setExitCode(name === null ? 2 : 0);
+    });
+    keys
+        .command("list")
+        .description("List the NAMES stored in the user store. Values are never printed.")
+        .option("--json", JSON_OPTION_DESCRIPTION)
+        .action(async (_options, command) => {
+        const storePath = userKeyStorePath(process.env);
+        const names = listUserKeys(process.env);
+        const result = {
+            schema: KEYS_RESULT_SCHEMA,
+            ok: true,
+            action: "list",
+            store: storePath,
+            names,
+            message: names.length === 0
+                ? "The store is empty. Add a key with `humanish keys set <vendor>`."
+                : `${names.length} key name(s) stored. Values are never printed.`,
+        };
+        writeResult(command, io, result, formatKeysHuman);
+        io.setExitCode(0);
+    });
+}
+function formatDoctorHuman(result) {
+    return ([
+        `humanish doctor ${result.ok ? "ok" : "needs setup"}`,
+        `cwd: ${result.cwd}`,
+        // "missing" is a VERDICT, and a row that never ran has none. A participant reading doctor on a
+        // fresh desktop got `- missing package.json: package.json is present and safe to read`, which
+        // contradicts itself in eleven words (labs/tui-self-study.yaml).
+        ...result.checks.map((check) => `- ${check.ok ? "ok" : check.checked === false ? "not checked" : "missing"} ${check.name}: ${check.message}`),
+    ].join("\n") + "\n");
+}
+function formatInitHuman(result) {
+    const title = result.ok ? `humanish init ${result.mode}` : `humanish init ${result.mode} blocked`;
+    const lines = [title, `cwd: ${result.cwd}`];
+    if (result.ok && result.mode === "applied") {
+        // A successful setup should leave its next action on the first terminal screen.
+        // Dry-runs and refusals retain their full plan; JSON always retains every change.
+        const counts = new Map();
+        for (const change of result.changes) {
+            counts.set(change.action, (counts.get(change.action) ?? 0) + 1);
+        }
+        const labels = {
+            create: "created",
+            mkdir: "directories prepared",
+            update: "updated",
+            skip: "preserved",
+        };
+        lines.push("", `changes: ${[...counts].map(([action, count]) => `${count} ${labels[action]}`).join(", ")}`, "Use humanish init --dry-run --json to inspect all files.");
+    }
+    else {
+        lines.push("", "changes:", ...result.changes.map(formatInitChange));
+    }
+    if (result.warnings.length > 0) {
+        lines.push("", "warnings:", ...result.warnings.map((warning) => `- ${warning}`));
+    }
+    if (result.error) {
+        lines.push("", `${result.error.code}: ${result.error.message}`);
+    }
+    if (result.mode === "needs-confirmation") {
+        lines.push("", "Run with --dry-run --json to inspect or --yes to apply.");
+    }
+    else if (result.ok && result.nextSteps !== undefined) {
+        // Twenty files and no next step is where the funnel died (#505). Increasingly the reader here
+        // is a coding agent doing setup for someone, and an agent does what stdout tells it to.
+        lines.push(...result.nextSteps);
+    }
+    return `${lines.join("\n")}\n`;
+}
+function formatInitChange(change) {
+    return `- ${change.action.padEnd(6)} ${change.path} (${change.target}: ${change.reason})`;
+}