humanish 0.49.0 → 0.50.0

package/dist/program.d.ts

@@ -2,6 +2,7 @@ import { Command } from "commander";
 import { discoverProviderKeys } from "./key-resolution.js";
 import type { ObserverResult, ObserverServer } from "./observer.js";
 import type { OssMetaLabResult } from "./oss-meta-lab.js";
+import { type TuiModule } from "./tui-contract.js";
 export declare const CLI_RESPONSE_SCHEMA = "humanish.cli-response.v1";
 export interface CliIo {
     writeOut(text: string): void;
@@ -18,7 +19,20 @@ export interface UnexpectedErrorEnvelope {
 }
 export declare function createProgram(io?: Partial<CliIo> & {
     keyDiscovery?: typeof discoverProviderKeys;
+    tuiRuntime?: Partial<TuiRuntime>;
 }): Command;
+/**
+ * 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 {
+    stdin: NodeJS.ReadStream;
+    stdout: NodeJS.WriteStream;
+    nodeVersion: string;
+    /** Resolves the bundle, or null when it is not present. */
+    loadTui(bundle: URL): Promise<TuiModule | null>;
+}
 /**
  * Default browser-open policy for a lab backend run. Mirrors the observe/watch gate:
  * an explicit --open/--no-open wins; --json (machine mode) never auto-opens; otherwise a

package/dist/program.js

@@ -1,4 +1,4 @@
-import { readFileSync } from "node:fs";
+import { existsSync, readFileSync } from "node:fs";
 import { formatOrientationHuman, readOrientation } from "./orientation.js";
 import { readFile } from "node:fs/promises";
 import { dirname, join, resolve } from "node:path";
@@ -24,6 +24,10 @@ import { DEFAULT_OSS_REPOS, runOssLab } from "./oss-lab.js";
 import { cleanupOssMetaLabSandboxes, cleanupStaleOssMetaLabSandboxes, runOssMetaLab, startOssMetaLabLiveRefresh } from "./oss-meta-lab.js";
 import { cleanupRun, doctor, listRuns, readReview, runDryRun, verifyRun } from "./run.js";
 import { reclaimRunSandboxes } from "./reclaim.js";
+import { RunIndexCache, readRunIndex } from "./run-index.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 { 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";
@@ -138,6 +142,7 @@ function reportUnexpectedActionError(command, io, error) {
 export function createProgram(io = {}) {
     const cliIo = { ...defaultIo, ...io };
     keyDiscoveryFn = io.keyDiscovery ?? discoverProviderKeys;
+    tuiRuntime = { ...defaultTuiRuntime, ...io.tuiRuntime };
     const program = new HumanishCommand(undefined, cliIo);
     // Bare `humanish` orients instead of printing sixteen subcommands (#367). --help is untouched;
     // this is only what happens when no command was chosen at all.
@@ -179,6 +184,7 @@ export function createProgram(io = {}) {
     ].join("\n"));
     registerInitCommand(program, cliIo);
     registerDoctorCommand(program, cliIo);
+    registerTuiCommand(program, cliIo);
     registerKeysCommand(program, cliIo);
     registerRunCommand(program, cliIo);
     registerVerifyCommand(program, cliIo);
@@ -237,6 +243,104 @@ function registerDoctorCommand(parent, io) {
         io.setExitCode(result.ok ? 0 : 2);
     });
 }
+const defaultTuiRuntime = {
+    stdin: process.stdin,
+    stdout: process.stdout,
+    nodeVersion: process.version,
+    loadTui: async (bundle) => {
+        if (!existsSync(bundle))
+            return null;
+        return (await import(bundle.href));
+    }
+};
+let tuiRuntime = defaultTuiRuntime;
+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.
+ */
+function registerTuiCommand(parent, io) {
+    parent
+        .command("tui")
+        .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("--json", JSON_OPTION_DESCRIPTION)
+        .action(async (options, command) => {
+        const { stdin, stdout } = tuiRuntime;
+        if (stdin.isTTY !== true || stdout.isTTY !== true) {
+            refuseTui(command, io, {
+                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."
+                }
+            });
+            return;
+        }
+        if (!nodeSupportsTui(tuiRuntime.nodeVersion)) {
+            refuseTui(command, io, {
+                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 ${tuiRuntime.nodeVersion}). Every other humanish command still works on this runtime.`
+                }
+            });
+            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 = tuiBundleUrl(import.meta.url);
+        const runIndexCache = new RunIndexCache();
+        const loaded = await tuiRuntime.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 exitCode = await loaded.startTui({
+            cwd: resolve(options.cwd),
+            version: { cli: CLI_VERSION },
+            capabilities: {
+                // 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: launchRun,
+                readLaunchLog: readLaunchLogTail,
+                readRunDetail
+            },
+            stdin,
+            stdout
+        });
+        // The surface owned the screen; it has already told the operator whatever there was to say.
+        markInvocationEnvelopeWritten(command);
+        io.setExitCode(exitCode);
+    });
+}
 // The discovery fn the env seam calls; injectable via createProgram for hermetic CLI tests.
 let keyDiscoveryFn = discoverProviderKeys;
 const KEYS_RESULT_SCHEMA = "humanish.keys-result.v1";
@@ -1755,6 +1859,11 @@ async function runLabCommand(args) {
         args.io.writeErr(`warning: ${warning}\n`);
     }
     const config = resolved.config;
+    // The run's identity (#455): which manifest, where it lives, and whether it is committed, a
+    // local overlay, or an explicit path. Resolved once here — the only place that knows all three —
+    // and carried into the run's status record and bundle so the filesystem can answer "which lab
+    // produced this run" without the old `persona.source = "lab:<id>"` string convention.
+    const lab = { id: config.id, path: resolved.path, origin: resolved.origin };
     const backend = selectLabBackend(config);
     if (backend !== "cua" && labRerunFlagsRequested(args.options)) {
         writeUnsupportedRerunFlagsResult(args, backend);
@@ -1806,28 +1915,28 @@ async function runLabCommand(args) {
     }
     switch (backend) {
         case "synthetic":
-            await runSyntheticBackend({ ...args, config });
+            await runSyntheticBackend({ ...args, config, labProvenance: lab });
             return;
         case "meta":
-            await runMetaBackend({ ...args, config });
+            await runMetaBackend({ ...args, config, labProvenance: lab });
             return;
         case "smoke":
-            await runSmokeBackend({ ...args, config });
+            await runSmokeBackend({ ...args, config, labProvenance: lab });
             return;
         case "cua":
-            await runCuaBackend({ ...args, config, ...(scorer ? { scorer } : {}) });
+            await runCuaBackend({ ...args, config, labProvenance: lab, ...(scorer ? { scorer } : {}) });
             return;
         case "scripted":
-            await runScriptedBackend({ ...args, config });
+            await runScriptedBackend({ ...args, config, labProvenance: lab });
             return;
         case "terminal":
-            await runTerminalBackend({ ...args, config, ...(scorer ? { scorer } : {}) });
+            await runTerminalBackend({ ...args, config, labProvenance: lab, ...(scorer ? { scorer } : {}) });
             return;
         case "shared-world":
-            await runSharedWorldBackend({ ...args, config, ...(scorer ? { scorer } : {}) });
+            await runSharedWorldBackend({ ...args, config, labProvenance: lab, ...(scorer ? { scorer } : {}) });
             return;
         case "concurrent-shared-world":
-            await runConcurrentSharedWorldBackend({ ...args, config, ...(scorer ? { scorer } : {}) });
+            await runConcurrentSharedWorldBackend({ ...args, config, labProvenance: lab, ...(scorer ? { scorer } : {}) });
             return;
         default:
             // Compile-time exhaustiveness: a future backend must be handled here, not silently no-op.
@@ -1870,6 +1979,7 @@ async function runSyntheticBackend(args) {
     }
     const outcome = await runLab(args.config, {
         cwd: args.options.cwd,
+        ...(args.labProvenance === undefined ? {} : { lab: args.labProvenance }),
         count: simCount,
         ...(args.options.dryRun === undefined ? {} : { dryRun: args.options.dryRun }),
         ...(args.options.runId === undefined ? {} : { runId: args.options.runId })
@@ -1977,6 +2087,7 @@ async function runCuaBackend(args) {
     try {
         outcome = await runLab(args.config, {
             cwd: args.options.cwd,
+            ...(args.labProvenance === undefined ? {} : { lab: args.labProvenance }),
             // Watch mode opens the served Observer below (or prints the phone target under --expose)
             // instead of the static render — preserved byte-for-byte from the pre-0.18 open policy so a
             // non-follow watch (dry-run/--json) does not double-open. Run mode keeps the static open.
@@ -2112,6 +2223,7 @@ async function runScriptedBackend(args) {
     });
     const outcome = await runLab(args.config, {
         cwd: args.options.cwd,
+        ...(args.labProvenance === undefined ? {} : { lab: args.labProvenance }),
         // Watch mode opens the served Observer below instead of the static render.
         open: args.mode === "watch" ? false : shouldOpen,
         ...(args.options.dryRun === undefined ? {} : { dryRun: args.options.dryRun }),
@@ -2148,6 +2260,7 @@ async function runTerminalBackend(args) {
     });
     const outcome = await runLab(args.config, {
         cwd: args.options.cwd,
+        ...(args.labProvenance === undefined ? {} : { lab: args.labProvenance }),
         open: args.mode === "watch" ? false : shouldOpen,
         ...(args.options.dryRun === undefined ? {} : { dryRun: args.options.dryRun }),
         ...(args.options.runId === undefined ? {} : { runId: args.options.runId }),
@@ -2181,6 +2294,7 @@ async function runSharedWorldBackend(args) {
     });
     const outcome = await runLab(args.config, {
         cwd: args.options.cwd,
+        ...(args.labProvenance === undefined ? {} : { lab: args.labProvenance }),
         open: args.mode === "watch" ? false : shouldOpen,
         ...(args.options.dryRun === undefined ? {} : { dryRun: args.options.dryRun }),
         ...(args.options.runId === undefined ? {} : { runId: args.options.runId }),
@@ -2262,6 +2376,7 @@ async function runConcurrentSharedWorldBackend(args) {
     try {
         outcome = await runLab(args.config, {
             cwd: args.options.cwd,
+            ...(args.labProvenance === undefined ? {} : { lab: args.labProvenance }),
             open: wantsFollow ? false : shouldOpen,
             dryRun,
             ...(wantsFollow
@@ -2423,6 +2538,7 @@ async function runSmokeBackend(args) {
     const repos = labReposOverride(args.options);
     const outcome = await runLab(args.config, {
         cwd: args.options.cwd,
+        ...(args.labProvenance === undefined ? {} : { lab: args.labProvenance }),
         count: limit,
         ...(repos === undefined ? {} : { repos }),
         ...(args.options.keep === undefined ? {} : { keep: args.options.keep }),
@@ -2479,6 +2595,8 @@ async function runMetaBackend(args) {
     try {
         const outcome = await runLab(args.config, {
             cwd: args.options.cwd,
+            ...(args.labProvenance === undefined ? {} : { lab: args.labProvenance }),
+            ...(args.labProvenance === undefined ? {} : { lab: args.labProvenance }),
             ...(wantsFollow ? { completionTimeoutMs: 0 } : {}),
             ...(codexAppServer === undefined ? {} : { codexAppServer }),
             ...(wantsFollow