humanish 0.55.0 → 0.57.0

package/dist/program.js

@@ -31,6 +31,8 @@ import { openObserverArtifact, stopRun } from "./tui-actions.js";
 import { readRunDetail } from "./run-detail.js";
 import { launchRun, readLaunchLogTail } from "./tui-launch.js";
 import { TUI_MIN_NODE_MAJOR, nodeSupportsTui, tuiBundleUrl } from "./tui-contract.js";
+import { forTerminal } from "./terminal-encoding.js";
+import { detectAgentSession } from "./agent-session.js";
 import { runCommsCatchHost } from "./comms-catch-host.js";
 import { DEFAULT_SANDBOX_CATCH_PORT } from "./comms-sandbox-catch.js";
 export const CLI_RESPONSE_SCHEMA = "humanish.cli-response.v1";
@@ -43,9 +45,14 @@ const CLI_VERSION = readCliVersion();
 // Shared so the ~20 leaf commands that declare their own --json flag cannot drift
 // from each other in wording.
 const JSON_OPTION_DESCRIPTION = "Print a machine-readable JSON response.";
+// Transcode ONLY for a terminal. A pipe carries bytes to another program — mangling those would
+// corrupt a JSON payload for a reader that handles UTF-8 perfectly well — while a TTY carries them
+// to a font, through a locale that may not decode them. See src/terminal-encoding.ts for what a
+// participant actually read back off the screen.
+const forStream = (stream, text) => stream.isTTY === true ? forTerminal(text) : text;
 const defaultIo = {
-    writeOut: (text) => process.stdout.write(text),
-    writeErr: (text) => process.stderr.write(text),
+    writeOut: (text) => process.stdout.write(forStream(process.stdout, text)),
+    writeErr: (text) => process.stderr.write(forStream(process.stderr, text)),
     setExitCode: (code) => {
         process.exitCode = code;
     }
@@ -142,6 +149,41 @@ function reportUnexpectedActionError(command, io, error) {
     }
     io.setExitCode(2);
 }
+/** `unknown option '--x'` -> the sibling commands that DO declare `--x`. */
+function commandsDeclaring(root, flag) {
+    const found = [];
+    const walk = (command, trail) => {
+        const names = [...trail, command.name()];
+        if (trail.length > 0 && command.options.some((option) => option.long === flag || option.short === flag)) {
+            found.push(names.slice(1).join(" "));
+        }
+        for (const child of command.commands)
+            walk(child, names);
+    };
+    walk(root, []);
+    return found;
+}
+/**
+ * Enrich commander's flag rejections with where the flag actually lives. A bare "unknown option"
+ * is accurate and unhelpful in the same way `no labs here yet` was: it reports a fact about this
+ * command and says nothing the reader can act on. Silence is preserved when no sibling has it —
+ * inventing a suggestion would be worse than none.
+ */
+export function withSiblingFlagHint(text, root) {
+    const match = /unknown option '([^']+)'/.exec(text);
+    if (match === null)
+        return text;
+    const owners = commandsDeclaring(root, match[1]);
+    if (owners.length === 0)
+        return text;
+    // Truncation is REPORTED, never silent: a list that quietly drops owners would send a reader
+    // looking in the wrong place and think it had answered them.
+    const shown = owners.slice(0, 3);
+    const list = shown.map((owner) => `\`humanish ${owner}\``).join(", ");
+    const rest = owners.length - shown.length;
+    const tail = rest > 0 ? ` (and ${rest} more)` : "";
+    return `${text.replace(/\n+$/, "")}\n${match[1]} is an option of ${list}${tail}, not of this command.\n`;
+}
 export function createProgram(io = {}) {
     const cliIo = { ...defaultIo, ...io };
     keyDiscoveryFn = io.keyDiscovery ?? discoverProviderKeys;
@@ -167,7 +209,14 @@ export function createProgram(io = {}) {
         .option("--json", "Print machine-readable JSON responses where supported.")
         .configureOutput({
         writeOut: (text) => cliIo.writeOut(text),
-        writeErr: (text) => cliIo.writeErr(text)
+        writeErr: (text) => cliIo.writeErr(text),
+        // A rejected flag should name the command that WOULD have taken it. Found by a real
+        // first-contact study (labs/first-contact.yaml): a participant reached for
+        // `humanish run --no-open` by analogy with `lab run`, got a bare "unknown option", and
+        // filed it as a documentation mismatch. The flag is genuinely absent — `run` opens
+        // nothing — but "unknown" says that badly, because the reader's actual question is
+        // "then where does it live?".
+        outputError: (text, write) => write(withSiblingFlagHint(text, program))
     })
         .addHelpText("after", [
         "",
@@ -249,6 +298,7 @@ function registerDoctorCommand(parent, io) {
 const defaultTuiRuntime = {
     stdin: process.stdin,
     stdout: process.stdout,
+    env: process.env,
     nodeVersion: process.version,
     loadTui: async (bundle) => {
         if (!existsSync(bundle))
@@ -283,9 +333,31 @@ function registerTuiCommand(parent, io) {
         .description("Open the interactive terminal surface for browsing labs and runs (humans only).")
         .summary("Open the interactive terminal surface.")
         .option("--cwd <path>", "Target project directory.", ".")
+        .option("--force", "Open it anyway in a session that looks like an agent's.")
         .option("--json", JSON_OPTION_DESCRIPTION)
         .action(async (options, command) => {
         const { stdin, stdout } = tuiRuntime;
+        // 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
+        // (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 = options.force === true ? undefined : detectAgentSession(tuiRuntime.env);
+        if (agent !== undefined) {
+            refuseTui(command, io, {
+                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 studies in this project, "
+                        + "and `humanish lab run <lab> --json` starts one. If you are a person at this keyboard, add --force."
+                }
+            });
+            return;
+        }
         if (stdin.isTTY !== true || stdout.isTTY !== true) {
             refuseTui(command, io, {
                 schema: TUI_RESULT_SCHEMA,
@@ -2811,7 +2883,10 @@ function formatDoctorHuman(result) {
     return [
         `humanish doctor ${result.ok ? "ok" : "needs setup"}`,
         `cwd: ${result.cwd}`,
-        ...result.checks.map((check) => `- ${check.ok ? "ok" : "missing"} ${check.name}: ${check.message}`)
+        // "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 formatRunHuman(result) {