humanish 0.106.1 → 0.108.0

package/dist/substrates/e2b/desktop-screenshot-cleanup.js

@@ -11,12 +11,12 @@ export function desktopScreenshotCleanupFailures(desktop) {
 /**
  * @e2b/desktop 2.3.3 screenshot() awaits capture and files.read(path), then discards the
  * files.remove(path) promise. A removal that races sandbox teardown can therefore crash Node
- * AFTER valid bytes were returned. Installed-SDK conformance tests pin that behavior (#662).
+ * after valid bytes were returned. Installed-SDK conformance tests pin that behavior.
  *
- * Observe only removal of a file successfully read within THIS screenshot invocation. The
+ * Observe only removal of a file successfully read within this screenshot invocation. The
  * exact path comes from the SDK, not a guessed filename pattern. AsyncLocalStorage isolates
  * concurrent screenshots and unrelated file operations without changing SDK method receivers.
- * The ORIGINAL removal promise is returned: an SDK version (or caller) that awaits it still
+ * The original removal promise is returned: an SDK version (or caller) that awaits it still
  * receives the original rejection. No process-wide rejection handler or filesystem retry.
  */
 export function protectDesktopScreenshotCleanup(desktop) {

package/dist/substrates/e2b/sandbox.d.ts

@@ -89,7 +89,7 @@ export declare const TRANSIENT_RETRY_DELAY_MS = 3000;
  *   describing, the same routing gap seen from the upload side.
  * - transport resets (`fetch failed`, `ECONNRESET`, `socket hang up`, 502/503/504).
  *
- * NOT retried: timeouts (the budget is spent), auth (401/403), quota and rate limits (429: a burst
+ * Not retried: timeouts (the budget is spent), auth (401/403), quota and rate limits (429: a burst
  * that hit the limit should be spaced, not repeated), and anything that names the request as wrong.
  */
 export declare function isTransientE2BError(error: unknown): boolean;

package/dist/substrates/e2b/sandbox.js

@@ -27,7 +27,7 @@ async function acquire(request, template) {
         if (request.receipt !== null) {
             const { root, participantId, now = Date.now } = request.receipt;
             // Best effort by contract: a failed write leaves the TTL as the only backstop and never
-            // fails the lane.
+            // fails the participant.
             await appendSandboxReceipt(root, {
                 at: new Date(now()).toISOString(),
                 laneId: participantId,
@@ -181,7 +181,7 @@ export const TRANSIENT_RETRY_DELAY_MS = 3_000;
  *   describing, the same routing gap seen from the upload side.
  * - transport resets (`fetch failed`, `ECONNRESET`, `socket hang up`, 502/503/504).
  *
- * NOT retried: timeouts (the budget is spent), auth (401/403), quota and rate limits (429: a burst
+ * Not retried: timeouts (the budget is spent), auth (401/403), quota and rate limits (429: a burst
  * that hit the limit should be spaced, not repeated), and anything that names the request as wrong.
  */
 export function isTransientE2BError(error) {

package/dist/substrates/e2b/sdk.d.ts

@@ -3,7 +3,7 @@ export interface E2BDesktopModule {
         /** The stock `desktop` template (no custom image). */
         create(options: E2BDesktopCreateOptions): Promise<E2BDesktopSandbox>;
         /**
-         * Launch on a CUSTOM E2B desktop template (image) by NAME or ID — the SDK's
+         * Launch on a custom E2B desktop template (image) by name or ID: the SDK's
          * `Sandbox.create(template, opts)` overload. Lets a lab run on an adopter-maintained image
          * with extra runtimes baked in (e.g. node/bun/a local Postgres the stock `desktop` template
          * lacks), instead of the stock template. The base @e2b/desktop SDK implements this; the
@@ -11,17 +11,17 @@ export interface E2BDesktopModule {
          */
         create(template: string, options: E2BDesktopCreateOptions): Promise<E2BDesktopSandbox>;
         /**
-         * Kill the sandbox specified by exact id. Returns true iff THAT sandbox was found and
-         * killed, false otherwise (the SDK's own doc comment). This boolean is the PRIMARY by-id
+         * Kill the sandbox specified by exact id. Returns true iff that sandbox was found and
+         * killed, false otherwise (the SDK's own doc comment). This boolean is the primary by-id
          * cleanup proof: a caller never needs to re-list to confirm reclamation.
          */
         kill?(sandboxId: string, options?: {
             requestTimeoutMs?: number;
         }): Promise<boolean>;
         /**
-         * Fetch ONE sandbox by its exact id (never account-wide). Throws a SandboxNotFoundError-
+         * Fetch one sandbox by its exact id (never account-wide). Throws a SandboxNotFoundError-
          * shaped error (see isSandboxNotFoundError below) when the id no longer exists; that thrown
-         * error IS the by-id confirmation that a killed sandbox is gone. Optional: older SDKs may
+         * error is the by-id confirmation that a killed sandbox is gone. Optional: older SDKs may
          * lack it, so callers fall back to kill()'s own boolean rather than ever calling Sandbox.list.
          */
         getInfo?(sandboxId: string, options?: {
@@ -123,10 +123,10 @@ export interface E2BDesktopSandbox {
     /** Open a file or URL with the desktop's default application (present on @e2b/desktop >= 1.x). */
     open?(fileOrUrl: string): Promise<void>;
     /**
-     * Map an in-sandbox port to a reachable host URL — `https://<port>-<sandboxId>.e2b.app`,
-     * TOKENLESS (no authKey, unlike `stream.getUrl`). The base `e2b` SDK (v2.27.0) implements this;
-     * the wrapper just exposes it. Used by the CONCURRENT shared-world topology (#164 phase 2) to
-     * expose the ONE subject service plane to N actor sandboxes. Optional: older SDKs may lack it, so
+     * Map an in-sandbox port to a reachable host URL, `https://<port>-<sandboxId>.e2b.app`,
+     * tokenless (no authKey, unlike `stream.getUrl`). The base `e2b` SDK (v2.27.0) implements this;
+     * the wrapper just exposes it. Used by the concurrent shared-world topology to
+     * expose the one subject service plane to N actor sandboxes. Optional: older SDKs may lack it, so
      * the concurrent backend fails closed when it is absent rather than calling a missing method.
      */
     getHost?(port: number): string;
@@ -169,7 +169,7 @@ export declare class E2BDesktopStartupError extends Error {
     constructor(error: unknown, cleanup: DesktopCreateCleanup, cleanupDetail?: string | undefined);
 }
 /**
- * Preserve ownership before the desktop SDK starts Xvfb/XFCE (#581). Its public generic create
+ * Preserve ownership before the desktop SDK starts Xvfb/XFCE. Its public generic create
  * constructs `new this(...)` through the base SDK, then awaits desktop startup. Newer SDKs
  * attempt their own kill before rejecting create; older SDKs leave cleanup to the caller.
  * Both paths share one bounded cleanup result so an internal kill cannot delay our deadline
@@ -183,7 +183,7 @@ export declare class E2BDesktopStartupError extends Error {
  */
 export declare function guardDesktopSandboxCreate(module: E2BDesktopModule): E2BDesktopModule;
 /**
- * Detect a SandboxNotFoundError-shaped error from the real @e2b/desktop SDK, WITHOUT importing
+ * Detect a SandboxNotFoundError-shaped error from the real @e2b/desktop SDK, without importing
  * its class (this module stays optional-peer / lazily-loaded, same as everything else here).
  * The real SDK sets `this.name = "SandboxNotFoundError"` on the class (it extends the
  * deprecated NotFoundError), so checking `.name` is the stable, import-free detection contract.

package/dist/substrates/e2b/sdk.js

@@ -2,8 +2,8 @@
 // real @e2b/desktop Sandbox. Every desktop route launches through this one seam; the peer dep is
 // optional and lazily loaded, so it stays out of the published tarball and CI.
 //
-// E2BDesktopSandbox is the command, file, stream, launch and input subset the lanes use; `open` is
-// optional because older SDKs lack it (the computer-use lane then falls back to launch). It
+// E2BDesktopSandbox is the command, file, stream, launch and input subset the participants use; `open` is
+// optional because older SDKs lack it (the computer-use route then falls back to launch). It
 // satisfies the executor's E2BDesktopLike port (src/substrates/e2b/desktop-executor.ts) as is.
 import { sep } from "node:path";
 import { fileURLToPath } from "node:url";
@@ -18,8 +18,8 @@ export async function loadE2BDesktopModule() {
                 ? "Live E2B desktop launch requires the optional peer @e2b/desktop. Install it beside humanish " +
                     "in this project: `npm i -D @e2b/desktop`."
                 : "Live E2B desktop launch requires the optional peer @e2b/desktop, and humanish is running from an " +
-                    "npx cache rather than from this project — so installing the peer here cannot help, because Node " +
-                    "resolves it relative to humanish itself. Install BOTH into the project and run it from there: " +
+                    "npx cache. Node resolves the peer relative to humanish itself, so a copy installed in this project " +
+                    "is not found. Install both into the project and run it from there: " +
                     "`npm i -D humanish @e2b/desktop` then `npx humanish run <lab>`.");
         }
         throw error;
@@ -44,7 +44,7 @@ export class E2BDesktopStartupError extends Error {
     }
 }
 /**
- * Preserve ownership before the desktop SDK starts Xvfb/XFCE (#581). Its public generic create
+ * Preserve ownership before the desktop SDK starts Xvfb/XFCE. Its public generic create
  * constructs `new this(...)` through the base SDK, then awaits desktop startup. Newer SDKs
  * attempt their own kill before rejecting create; older SDKs leave cleanup to the caller.
  * Both paths share one bounded cleanup result so an internal kill cannot delay our deadline
@@ -147,8 +147,8 @@ async function reclaimFailedDesktopCreate(kill, timeoutMs) {
 /**
  * Is humanish running from this project's node_modules, or from an npx cache?
  *
- * It decides which advice is TRUE. `npx humanish@latest` resolves its optional peer relative to
- * ITSELF, so "install @e2b/desktop in this project" is advice that cannot work there — and that
+ * It decides which advice is true. `npx humanish@latest` resolves its optional peer relative to
+ * itself, so "install @e2b/desktop in this project" is advice that cannot work there, and that
  * message cost two cold verification runs before the difference was noticed. A one-shot npx
  * invocation cannot do a live desktop run at all; humanish has to be installed alongside the peer.
  */
@@ -161,7 +161,7 @@ function isMissingE2BDesktopDependency(error) {
     return value.code === "ERR_MODULE_NOT_FOUND" && value.message?.includes("@e2b/desktop") === true;
 }
 /**
- * Detect a SandboxNotFoundError-shaped error from the real @e2b/desktop SDK, WITHOUT importing
+ * Detect a SandboxNotFoundError-shaped error from the real @e2b/desktop SDK, without importing
  * its class (this module stays optional-peer / lazily-loaded, same as everything else here).
  * The real SDK sets `this.name = "SandboxNotFoundError"` on the class (it extends the
  * deprecated NotFoundError), so checking `.name` is the stable, import-free detection contract.

package/dist/substrates/local/runtime-host.d.ts

@@ -16,6 +16,8 @@ export declare function runtimeExec(file: string, args: string[], options?: Runt
     stdout: string;
     stderr: string;
 }>;
+/** The shell command an operator runs for `docker <args>` on this host, as runtimeDocker runs it. */
+export declare function dockerCommandLine(args: string[], options?: RuntimeHostOptions): string;
 export declare function runtimeDocker(args: string[], options?: RuntimeHostOptions, timeout?: number): Promise<{
     stdout: string;
     stderr: string;

package/dist/substrates/local/runtime-host.js

@@ -30,6 +30,12 @@ export async function runtimeExec(file, args, options = {}, timeout = 15_000) {
         ? hostExec("limactl", ["shell", "--workdir", "/", LIMA_INSTANCE, "--", file, ...args], options, timeout)
         : hostExec(file, args, options, timeout);
 }
+/** The shell command an operator runs for `docker <args>` on this host, as runtimeDocker runs it. */
+export function dockerCommandLine(args, options = {}) {
+    return usesLima(options)
+        ? `limactl shell ${LIMA_INSTANCE} -- sudo docker --host unix:///var/run/docker.sock ${args.join(" ")}`
+        : `docker ${args.join(" ")}`;
+}
 export async function runtimeDocker(args, options = {}, timeout = 15_000) {
     return usesLima(options)
         ? runtimeExec("sudo", ["-n", "docker", "--host", "unix:///var/run/docker.sock", ...args], options, timeout)

package/dist/tui/actions.d.ts

@@ -25,15 +25,17 @@ export declare function createTuiObserverSession(cwdInput: string, options?: {
  * The counterpart to starting one: a study that is going nowhere costs money every turn, and until
  * now the only way to end it was to find the pid yourself.
  *
- * It signals the PROCESS GROUP, not the process. A run is spawned detached — its own group — and it
+ * It signals the process group, not the process. A run is spawned detached, in its own group, and it
  * has children: the CLI, and whatever it spawned to reach the sandbox. Signalling only the parent
  * leaves those orphaned and still working.
  *
- * SIGTERM, never SIGKILL: the run's own handlers get the chance to finalize its record and release
- * what it holds. A killed run leaves a `running` record to go stale, which reads as interrupted —
- * true, but strictly less informative than a run that was told to stop.
+ * SIGTERM, never SIGKILL, so the run's handler gets to act. Outside post-run analysis the run
+ * command (src/cli/commands/run-signals.ts) marks the run `interrupted` in status.json, kills the
+ * E2B sandboxes its receipts name, writes reclaim-receipt.json and exits; run.json keeps its last
+ * live flush. During analysis the signal cancels analysis instead. A local VM's container exits
+ * when the run's process goes.
  *
- * This stops the PROCESS. Sandboxes it created are a separate resource with their own receipts, and
- * `Reclaim` is what stops those — the run screen offers it as soon as this succeeds.
+ * `Reclaim` stays on offer: it retries by id any kill the handler could not confirm within its
+ * 10 s deadline. Each sandbox's create-time timeout is the backstop.
  */
 export declare function stopRun(cwd: string, runId: string, intent?: "run" | "analysis"): Promise<TuiActionResult>;

package/dist/tui/actions.js

@@ -1,9 +1,9 @@
-import { requestAutomaticStudyAnalysisCancellation } from "../analysis/automatic.js";
-// The two things a run card can DO (#455 rev 8).
+import { requestAutomaticAnalysisCancellation } from "../analysis/automatic.js";
+// The two things a run card can do.
 //
-// The mock's run screen is an outcome CARD with actions, not a field list, and an action that does
-// nothing is worse than no action — so this ships the two that are genuinely implementable today
-// and nothing else. `Share…` waits for the export contract (#471) rather than appearing as a
+// The mock's run screen is an outcome card with actions, not a field list, and an action that does
+// nothing is worse than no action, so this ships the two that are genuinely implementable today
+// and nothing else. `Share…` waits for the export contract rather than appearing as a
 // control that fails.
 import { readFile } from "node:fs/promises";
 import path from "node:path";
@@ -32,7 +32,7 @@ export function createTuiObserverSession(cwdInput, options = {}) {
     return {
         async open(targetCwd, observerPath) {
             if (closed)
-                return result(false, "this terminal session has closed — reopen humanish tui to view the run");
+                return result(false, "this terminal session has closed; reopen `humanish tui` to view the run");
             if (path.resolve(targetCwd) !== cwd)
                 return result(false, "Observer can only open runs from this terminal session's project");
             // The capability takes the run-card path, not an arbitrary file, URL, or second project.
@@ -58,7 +58,7 @@ export function createTuiObserverSession(cwdInput, options = {}) {
                 return result(false, "this run's evidence directory is missing or unsafe to open");
             }
             if (closed)
-                return result(false, "this terminal session has closed — reopen humanish tui to view the run");
+                return result(false, "this terminal session has closed; reopen `humanish tui` to view the run");
             try {
                 // Share the pending start too: two quick selections must not create two listeners.
                 serverPromise ??= serveObserverLibrary(cwd, {
@@ -78,13 +78,13 @@ export function createTuiObserverSession(cwdInput, options = {}) {
                 });
                 const server = await serverPromise;
                 if (closed)
-                    return result(false, "this terminal session has closed — reopen humanish tui to view the run");
+                    return result(false, "this terminal session has closed; reopen `humanish tui` to view the run");
                 const url = new URL(`_humanish/runs/${encodeURIComponent(runId)}/observer/index.html`, server.url).href;
                 const opened = open(url);
-                return result(true, `${url} — follows saved captures; keep this TUI open.${opened.warning ? ` ${opened.warning}` : " If no browser appeared, open this URL on this machine or forward its port over SSH."}`);
+                return result(true, `${url} follows saved captures while you keep this TUI open.${opened.warning ? ` ${opened.warning}` : " If no browser appeared, open this URL on this machine or forward its port over SSH."}`);
             }
             catch {
-                return result(false, "Observer could not start — try humanish observe --run with this run's id in another terminal");
+                return result(false, "Observer could not start; run `humanish observe --run <run id>` in another terminal");
             }
         },
         close() {
@@ -104,22 +104,24 @@ export function createTuiObserverSession(cwdInput, options = {}) {
  * The counterpart to starting one: a study that is going nowhere costs money every turn, and until
  * now the only way to end it was to find the pid yourself.
  *
- * It signals the PROCESS GROUP, not the process. A run is spawned detached — its own group — and it
+ * It signals the process group, not the process. A run is spawned detached, in its own group, and it
  * has children: the CLI, and whatever it spawned to reach the sandbox. Signalling only the parent
  * leaves those orphaned and still working.
  *
- * SIGTERM, never SIGKILL: the run's own handlers get the chance to finalize its record and release
- * what it holds. A killed run leaves a `running` record to go stale, which reads as interrupted —
- * true, but strictly less informative than a run that was told to stop.
+ * SIGTERM, never SIGKILL, so the run's handler gets to act. Outside post-run analysis the run
+ * command (src/cli/commands/run-signals.ts) marks the run `interrupted` in status.json, kills the
+ * E2B sandboxes its receipts name, writes reclaim-receipt.json and exits; run.json keeps its last
+ * live flush. During analysis the signal cancels analysis instead. A local VM's container exits
+ * when the run's process goes.
  *
- * This stops the PROCESS. Sandboxes it created are a separate resource with their own receipts, and
- * `Reclaim` is what stops those — the run screen offers it as soon as this succeeds.
+ * `Reclaim` stays on offer: it retries by id any kill the handler could not confirm within its
+ * 10 s deadline. Each sandbox's create-time timeout is the backstop.
  */
 export async function stopRun(cwd, runId, intent = "run") {
     // The selected action carries its authority. Never infer permission to signal a process from
     // mutable status metadata after the operator asked only to cancel analysis.
     if (intent === "analysis") {
-        const analysis = await requestAutomaticStudyAnalysisCancellation(cwd, runId);
+        const analysis = await requestAutomaticAnalysisCancellation(cwd, runId);
         return {
             schema: TUI_ACTION_SCHEMA,
             ok: analysis.requested,
@@ -142,7 +144,7 @@ export async function stopRun(cwd, runId, intent = "run") {
         return {
             schema: TUI_ACTION_SCHEMA,
             ok: false,
-            message: "this run has no status record, so there is no pid to stop — it predates the contract or never started",
+            message: "this run has no status record, so there is no pid to stop; it predates status records or never started",
         };
     }
     if (!isRunStatusRecord(record)) {
@@ -153,7 +155,7 @@ export async function stopRun(cwd, runId, intent = "run") {
         };
     }
     if (record.state === "finished") {
-        const analysis = await requestAutomaticStudyAnalysisCancellation(cwd, runId);
+        const analysis = await requestAutomaticAnalysisCancellation(cwd, runId);
         if (analysis.requested)
             return {
                 schema: TUI_ACTION_SCHEMA,
@@ -162,13 +164,20 @@ export async function stopRun(cwd, runId, intent = "run") {
             };
         return { schema: TUI_ACTION_SCHEMA, ok: false, message: "this run already finished" };
     }
+    if (record.state === "interrupted") {
+        return {
+            schema: TUI_ACTION_SCHEMA,
+            ok: false,
+            message: `this run already stopped (${record.signal ?? "interrupted"}); Reclaim releases any sandbox it left`,
+        };
+    }
     const pid = record.pid;
     if (typeof pid !== "number" || !Number.isInteger(pid) || pid <= 1) {
         // pid 1 and below are never a run of ours, and signalling them would be catastrophic.
         return { schema: TUI_ACTION_SCHEMA, ok: false, message: "this run recorded no usable pid" };
     }
     // Is it actually still there? A pid whose process is already gone means the run died without
-    // finalizing — nothing to stop, and the record will read as interrupted on its own.
+    // finalizing: nothing to stop, and the record will read as interrupted on its own.
     try {
         process.kill(pid, 0);
     }
@@ -176,7 +185,7 @@ export async function stopRun(cwd, runId, intent = "run") {
         return {
             schema: TUI_ACTION_SCHEMA,
             ok: false,
-            message: `nothing is running under pid ${pid} — it has already stopped, and its record will read as interrupted`,
+            message: `nothing is running under pid ${pid}; it has already stopped, and its record will read as interrupted`,
         };
     }
     try {
@@ -198,6 +207,6 @@ export async function stopRun(cwd, runId, intent = "run") {
     return {
         schema: TUI_ACTION_SCHEMA,
         ok: true,
-        message: "asked the run to stop — its sandboxes are separate, so Reclaim them once it reports interrupted",
+        message: "asked the run to stop; it marks itself interrupted and kills its E2B sandboxes, and Reclaim retries any kill it could not confirm",
     };
 }

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");