humanish 0.107.0 → 0.108.0

package/dist/tui/contract.d.ts

@@ -39,32 +39,32 @@ export interface TuiCapabilities {
     /** Read every run in the project, cheapest source first. */
     readRunIndex(cwd: string, options?: ReadRunIndexOptions): Promise<RunIndexResult>;
     /**
-     * The labs DECLARED in this project. Listed separately from run history because neither side is
+     * The labs declared in this project. Listed separately from run history because neither side is
      * the whole truth: a fresh project has manifests and no runs, and a long-lived one has runs from
      * manifests since renamed or deleted.
      */
     listLabs(cwd: string): Promise<LabListResult>;
     /**
-     * Start a run and return once it is running. The run is DETACHED: it outlives this surface, so
-     * quitting the TUI — or losing the connection it runs over — does not kill a study that costs
+     * Start a run and return once it is running. The run is detached: it outlives this surface, so
+     * quitting the TUI (or losing the connection it runs over) does not kill a study that costs
      * real money. The surface then follows it through `status.json` like any other reader.
      */
     startRun(options: Omit<LaunchRunOptions, "spawn" | "cliPath" | "now">): Promise<LaunchRunResult>;
     /** The tail of a launch log: the only account of a run that died before writing evidence. */
     readLaunchLog(logPath: string): Promise<string>;
     /**
-     * Who is in ONE run and what they are thinking. Opens that run's bundle, which the index
-     * deliberately does not — affordable because it is asked only for the run being watched.
+     * Who is in one run and what they are thinking. Opens that run's bundle, which the index
+     * deliberately does not. That is affordable because it is asked only for the run being watched.
      * `null` when the run has not written a bundle yet.
      */
     readRunDetail(cwd: string, runId: string): Promise<RunDetail | null>;
     /**
-     * What a lab IS — subject, participants, model, spend caps, and whether the keys a live run needs
+     * What a lab is: subject, participants, model, spend caps, and whether the keys a live run needs
      * resolve right now. Read for the lab being looked at, because it is what someone reads before
      * deciding to spend money.
      */
     readLabSummary(cwd: string, lab: string, options?: ReadLabSummaryOptions): Promise<LabSummary | null>;
-    /** Whether this directory is a humanish project — an empty project and a wrong directory are
+    /** Whether this directory is a humanish project: an empty project and a wrong directory are
      *  different problems and must not share a screen. */
     readProjectState(cwd: string): TuiProjectState;
     /** Open the selected run in the session-owned local evidence server; closes when the TUI exits. */
@@ -72,12 +72,12 @@ export interface TuiCapabilities {
     /** Stop the sandboxes an interrupted run left behind, keeping its evidence. */
     reclaimRun(cwd: string, runId: string): Promise<ReclaimResult>;
     /** End a run that is still going. "analysis" is marker-only regardless of the current status;
-     * it MUST NOT probe or signal a process. The default "run" intent stops the participant process. */
+     * it must not probe or signal a process. The default "run" intent stops the participant process. */
     stopRun(cwd: string, runId: string, intent?: "run" | "analysis"): Promise<TuiActionResult>;
     /**
-     * Set this directory up as a humanish project. The surface's only WRITING action outside of
-     * starting runs — offered because "cd somewhere else and run init" is a dead end shown to
-     * exactly the person who has just arrived (#505).
+     * Set this directory up as a humanish project. The surface's only writing action outside of
+     * starting runs, offered because "cd somewhere else and run init" is a dead end shown to
+     * exactly the person who has just arrived.
      */
     initProject(cwd: string): Promise<TuiActionResult>;
 }
@@ -100,7 +100,7 @@ export interface TuiOptions {
     exitAfterFirstFrame?: boolean;
 }
 /**
- * Start the surface. Resolves with the process exit code when the operator quits — the TUI owns the
+ * Start the surface. Resolves with the process exit code when the operator quits; the TUI owns the
  * screen until then, so the CLI must not write to stdout while this is pending.
  */
 export type TuiHandoff = {
@@ -125,14 +125,14 @@ export declare function nodeSupportsTui(versionString?: string): boolean;
  */
 export declare const TUI_BUNDLE_URL: import("url").URL;
 /**
- * What `doctor` says about the stakeholder surface — a pure function of the machine's state and,
- * crucially, of WHO IS READING.
+ * What `doctor` says about the stakeholder surface: a pure function of the machine's state and,
+ * crucially, of who is reading.
  *
  * A real first-contact study (labs/first-contact.yaml) is why the reader matters. An autonomous
  * 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
+ * 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 and 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
+ * 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 in the transcript.
  */
 export declare function terminalSurfaceMessage(state: {

package/dist/tui/contract.js

@@ -1,11 +1,11 @@
-// The boundary between the CLI and the terminal UI (#455).
+// The boundary between the CLI and the terminal UI.
 //
-// `humanish tui` loads a PRE-BUILT bundle (dist/tui-app.js) that contains Ink, React and the
-// screens — and nothing else. Everything the surface needs to KNOW is passed across this interface
+// `humanish tui` loads a pre-built bundle (dist/tui-app.js) that contains Ink, React and the
+// screens, and nothing else. Everything the surface needs to know is passed across this interface
 // by the CLI, which imports it from the same modules every other command uses.
 //
 // The reason for the seam: a terminal UI that reads the filesystem itself would become a second
-// implementation of "what is a run, which lab does it belong to, is it alive" — one that ships
+// implementation of "what is a run, which lab does it belong to, is it alive", one that ships
 // minified, is invisible to the root test suite, and drifts from `humanish runs` the first time
 // either side changes. Injection keeps exactly one implementation, already unit-tested, and leaves
 // the bundle a view layer that can be reasoned about as one.
@@ -29,14 +29,14 @@ export function nodeSupportsTui(versionString = process.version) {
  */
 export const TUI_BUNDLE_URL = new URL("../tui-app.js", import.meta.url);
 /**
- * What `doctor` says about the stakeholder surface — a pure function of the machine's state and,
- * crucially, of WHO IS READING.
+ * What `doctor` says about the stakeholder surface: a pure function of the machine's state and,
+ * crucially, of who is reading.
  *
  * A real first-contact study (labs/first-contact.yaml) is why the reader matters. An autonomous
  * 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
+ * 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 and 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
+ * 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 in the transcript.
  */
 export function terminalSurfaceMessage(state) {
@@ -44,9 +44,9 @@ export function terminalSurfaceMessage(state) {
         return `\`humanish tui\` needs Node ${TUI_MIN_NODE_MAJOR}+ (this is ${state.nodeVersion}); every other command works here`;
     }
     if (!state.bundlePresent) {
-        return "`humanish tui` bundle is not built in this checkout — run `pnpm build` (installed packages ship it prebuilt)";
+        return "`humanish tui` is not built in this checkout; run `pnpm build` (installed packages ship it prebuilt)";
     }
     return state.interactive
         ? "`humanish tui` opens the interactive surface for browsing labs and runs"
-        : "`humanish tui` is the interactive surface a PERSON uses to watch and start runs here — this shell is not a terminal, so pass it on to whoever is";
+        : "`humanish tui` is the interactive screen a person uses to watch and start runs here. This shell is not a terminal, so pass it on to a person at one";
 }

package/dist/tui/launch.d.ts

@@ -2,7 +2,7 @@ import { spawn } from "node:child_process";
 export declare function isSafeLabHandle(value: string): boolean;
 export interface LaunchRunOptions {
     cwd: string;
-    /** The manifest handle (filename stem), as `humanish lab run` takes it. */
+    /** The manifest handle (filename stem), as `humanish run` takes it. */
     lab: string;
     /** Exact selected manifest, avoiding a same-name committed lab shadowing a local copy. */
     manifestPath?: string;
@@ -19,7 +19,7 @@ export interface LaunchedRun {
     /** The spawned CLI's pid. The run's `status.json` stamps the same value. */
     pid: number;
     /**
-     * When the launch happened. A pid ALONE cannot identify a run: pids are recycled by the OS and a
+     * When the launch happened. A pid alone cannot identify a run: pids are recycled by the OS and a
      * finished run keeps its pid in `status.json` forever, so a week-old record can carry the pid the
      * kernel just handed this child. Anything matching on pid must also require the record to be
      * newer than this.
@@ -40,11 +40,11 @@ export type LaunchRunResult = {
         message: string;
     };
 };
-export type LaunchErrorCode = "HUMANISH_LAUNCH_INVALID_LAB" | "HUMANISH_LAUNCH_FAILED";
+export type LaunchErrorCode = "HUMANISH_LAUNCH_INVALID_STUDY" | "HUMANISH_LAUNCH_FAILED";
 /**
  * Start a run and return as soon as it is running. Never throws: a launch that cannot happen is a
  * result the surface can render, not an exception that would tear down the screen.
  */
 export declare function launchRun(options: LaunchRunOptions): Promise<LaunchRunResult>;
-/** Read the tail of a launch log — the only account of a run that died before writing evidence. */
+/** Read the tail of a launch log: the only account of a run that died before writing evidence. */
 export declare function readLaunchLogTail(logPath: string, maxBytes?: number): Promise<string>;

package/dist/tui/launch.js

@@ -1,14 +1,14 @@
-// Starting a run from the terminal surface (#455).
+// Starting a run from the terminal surface.
 //
-// THE RUN MUST OUTLIVE THE SURFACE. A study can take minutes and costs real money, so a run
+// The run must outlive the surface. A study can take minutes and costs real money, so a run
 // started from the TUI cannot be a child of the TUI's event loop: closing the surface, or losing
 // the SSH session it is running over, must not kill it. So this spawns the CLI the same way a
-// person would type it — detached, in its own process group, with its output going to a file
+// person would type it: detached, in its own process group, with its output going to a file
 // rather than to a terminal that may be about to disappear.
 //
 // The surface then learns what happened the same way any other reader does: from `status.json`.
 // It does not hold a handle to the run, parse its stdout, or track it in memory. That is what
-// makes the surface restartable — quit the TUI mid-run, reopen it, and the run is still there,
+// makes the surface restartable: quit the TUI mid-run, reopen it, and the run is still there,
 // because the filesystem was always the source of truth rather than a process handle.
 import { spawn } from "node:child_process";
 import { constants as fsConstants } from "node:fs";
@@ -18,14 +18,14 @@ import { fileURLToPath } from "node:url";
 import { resolveLabManifest } from "../lab/discover.js";
 import { prepareManagedHumanishOutputDirectory } from "../run/contained-output.js";
 /**
- * A lab handle is the manifest FILENAME, which is what `humanish lab run` resolves. Restricted to
- * characters a manifest name can actually contain, and — the part that matters — never allowed to
+ * A lab handle is the manifest filename, which is what `humanish run` resolves. Restricted to
+ * characters a manifest name can actually contain, and (the part that matters) never allowed to
  * begin with `-`, because argv is positional: a lab called `--json` would otherwise be handed to
  * the CLI as a flag. There is no shell involved, so this is the whole injection surface.
  *
- * A leading underscore IS allowed: `_wip.yaml` is an ordinary way to name a work-in-progress
- * manifest, `humanish lab run _wip` resolves it, and refusing it here would leave the surface
- * listing a lab it will not start. A leading dot stays out — that names a hidden file, not a lab.
+ * A leading underscore is allowed: `_wip.yaml` is an ordinary way to name a work-in-progress
+ * manifest, `humanish run _wip` resolves it, and refusing it here would leave the surface
+ * listing a lab it will not start. A leading dot stays out: that names a hidden file, not a lab.
  */
 const SAFE_LAB_HANDLE = /^[A-Za-z0-9_][A-Za-z0-9._:-]*$/;
 export function isSafeLabHandle(value) {
@@ -44,8 +44,8 @@ export async function launchRun(options) {
         return {
             ok: false,
             error: {
-                code: "HUMANISH_LAUNCH_INVALID_LAB",
-                message: `"${options.lab}" is not a usable lab handle. Run it by path with \`humanish lab run <path>\` instead.`,
+                code: "HUMANISH_LAUNCH_INVALID_STUDY",
+                message: `"${options.lab}" is not a usable lab handle. Run it by path with \`humanish run <path>\` instead.`,
             },
         };
     }
@@ -57,8 +57,8 @@ export async function launchRun(options) {
             return {
                 ok: false,
                 error: {
-                    code: "HUMANISH_LAUNCH_INVALID_LAB",
-                    message: "The selected lab path could not be read safely. Refresh the lab list.",
+                    code: "HUMANISH_LAUNCH_INVALID_STUDY",
+                    message: "The selected study path could not be read safely. Refresh the study list.",
                 },
             };
         selectedLab = path.relative(cwd, path.resolve(cwd, resolved.path)).replace(/\\/g, "/");
@@ -74,8 +74,8 @@ export async function launchRun(options) {
         const logDir = await prepareManagedHumanishOutputDirectory(cwd, "launches");
         const stamp = launchedAt.replace(/[:.]/g, "-");
         logPath = path.join(logDir.physicalPath, `${stamp}-${options.lab}.log`);
-        // O_NOFOLLOW so a symlink planted at this path cannot redirect a run's output — which may carry
-        // provider error text — outside the project, and cannot defeat the 0600 mode by pointing at a
+        // O_NOFOLLOW so a symlink planted at this path cannot redirect a run's output (which may carry
+        // provider error text) outside the project, and cannot defeat the 0600 mode by pointing at a
         // file that already exists with looser permissions. O_CREAT|O_APPEND keeps ordinary reuse
         // working; only a symlink is refused (ELOOP).
         handle = await open(logPath, fsConstants.O_CREAT | fsConstants.O_WRONLY | fsConstants.O_APPEND | fsConstants.O_NOFOLLOW, 0o600);
@@ -93,7 +93,6 @@ export async function launchRun(options) {
     // the operator's attention and must not have a browser thrown over it.
     const args = [
         options.cliPath ?? defaultCliPath(),
-        "lab",
         "run",
         "--cwd",
         cwd,
@@ -115,9 +114,9 @@ export async function launchRun(options) {
     };
     try {
         const child = spawnFn(process.execPath, args, spawnOptions);
-        // A spawn failure is delivered ASYNCHRONOUSLY as an 'error' event (EAGAIN, EMFILE, ENOMEM, a
+        // A spawn failure is delivered asynchronously as an 'error' event (EAGAIN, EMFILE, ENOMEM, a
         // vanished node binary). An 'error' event with no listener is re-thrown by EventEmitter as an
-        // uncaught exception — which would tear down the whole surface, the one thing this module
+        // uncaught exception, which would tear down the whole surface, the one thing this module
         // promises never to do. The run is already unref'd and unobserved, so recording it is all that
         // is available; the operator learns about it from the launch log and the missing record.
         child.on("error", () => {
@@ -151,7 +150,7 @@ export async function launchRun(options) {
         };
     }
 }
-/** Read the tail of a launch log — the only account of a run that died before writing evidence. */
+/** Read the tail of a launch log: the only account of a run that died before writing evidence. */
 export async function readLaunchLogTail(logPath, maxBytes = 4_000) {
     try {
         const handle = await open(logPath, "r");

package/dist/tui/project.js

@@ -1,9 +1,9 @@
-// Is this directory a humanish project at all? (#455)
+// Is this directory a humanish project at all?
 //
-// The surface has two very different empty states and used to render one screen for both. A
-// project with no labs yet needs "write one"; a directory that is not a project — someone's home
-// directory, because `npx humanish tui` is easy to type anywhere — needs to know that first. The
-// second is what Daniel hit, and being told "no labs here yet" in `~` reads as a broken tool.
+// The surface has two empty states and renders a different screen for each. A project with no
+// labs yet needs "write one"; a directory that is not a project (someone's home directory,
+// because `npx humanish tui` is easy to type anywhere) needs to know that first. Being told "no
+// labs here yet" in `~` reads as a broken tool.
 import { existsSync } from "node:fs";
 import path from "node:path";
 const TUI_PROJECT_SCHEMA = "humanish.tui-project.v1";