humanish 0.48.0 → 0.50.0

package/dist/tui-contract.d.ts

@@ -0,0 +1,73 @@
+import type { LabListResult } from "./labs.js";
+import type { RunDetail } from "./run-detail.js";
+import type { ReadRunIndexOptions, RunIndexResult } from "./run-index.js";
+import type { LaunchRunOptions, LaunchRunResult } from "./tui-launch.js";
+/** The humanish version string shown in the frame, so a screenshot in a bug report is datable. */
+export interface TuiVersionInfo {
+    cli: string;
+}
+/**
+ * What the surface may do to the project. Deliberately a small, explicit list rather than a handle
+ * to the whole library: the set of verbs a stakeholder surface can perform should be readable in
+ * one place, and anything absent here is something the TUI simply cannot do.
+ */
+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 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
+     * 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.
+     * `null` when the run has not written a bundle yet.
+     */
+    readRunDetail(cwd: string, runId: string): Promise<RunDetail | null>;
+}
+export interface TuiOptions {
+    /** The project the surface is reading. Already resolved by the CLI. */
+    cwd: string;
+    version: TuiVersionInfo;
+    capabilities: TuiCapabilities;
+    /**
+     * Terminal streams, injected so a test can drive the surface without a real TTY. The CLI passes
+     * the real ones; both are known to be TTYs by the time this is called, because the command
+     * refuses to start otherwise.
+     */
+    stdin: NodeJS.ReadStream;
+    stdout: NodeJS.WriteStream;
+    /** Test seam: render one frame and resolve, instead of waiting for the operator to quit. */
+    exitAfterFirstFrame?: boolean;
+}
+/**
+ * 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 StartTui = (options: TuiOptions) => Promise<number>;
+/** The shape `dist/tui-app.js` exports. Asserted at the load boundary in program.ts. */
+export interface TuiModule {
+    startTui: StartTui;
+}
+/** Node version the Ink runtime requires (ink@7 declares `engines.node >= 22`). */
+export declare const TUI_MIN_NODE_MAJOR = 22;
+/**
+ * Whether this runtime can host the surface. Kept here, beside the reason, so the CLI's refusal and
+ * `doctor`'s readiness row can never disagree about the answer.
+ */
+export declare function nodeSupportsTui(versionString?: string): boolean;
+/**
+ * Where the bundle sits relative to the compiled CLI. Shared so the command that loads it and the
+ * readiness row that reports it can never look in different places.
+ */
+export declare function tuiBundleUrl(baseUrl: string): URL;

package/dist/tui-contract.js

@@ -0,0 +1,32 @@
+// The boundary between the CLI and the terminal UI (#455).
+//
+// `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
+// 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.
+//
+// It also makes the UI testable without a terminal: a test hands `startTui` a fake index and reads
+// the frames back.
+/** Node version the Ink runtime requires (ink@7 declares `engines.node >= 22`). */
+export const TUI_MIN_NODE_MAJOR = 22;
+/**
+ * Whether this runtime can host the surface. Kept here, beside the reason, so the CLI's refusal and
+ * `doctor`'s readiness row can never disagree about the answer.
+ */
+export function nodeSupportsTui(versionString = process.version) {
+    const major = Number.parseInt(versionString.replace(/^v/, "").split(".")[0] ?? "", 10);
+    return Number.isFinite(major) && major >= TUI_MIN_NODE_MAJOR;
+}
+/**
+ * Where the bundle sits relative to the compiled CLI. Shared so the command that loads it and the
+ * readiness row that reports it can never look in different places.
+ */
+export function tuiBundleUrl(baseUrl) {
+    return new URL("./tui-app.js", baseUrl);
+}
+//# sourceMappingURL=tui-contract.js.map

package/dist/tui-contract.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"tui-contract.js","sourceRoot":"","sources":["../src/tui-contract.ts"],"names":[],"mappings":"AAAA,2DAA2D;AAC3D,EAAE;AACF,6FAA6F;AAC7F,mGAAmG;AACnG,+EAA+E;AAC/E,EAAE;AACF,gGAAgG;AAChG,+FAA+F;AAC/F,gGAAgG;AAChG,mGAAmG;AACnG,6DAA6D;AAC7D,EAAE;AACF,mGAAmG;AACnG,mBAAmB;AAqEnB,mFAAmF;AACnF,MAAM,CAAC,MAAM,kBAAkB,GAAG,EAAE,CAAC;AAErC;;;GAGG;AACH,MAAM,UAAU,eAAe,CAAC,gBAAwB,OAAO,CAAC,OAAO;IACrE,MAAM,KAAK,GAAG,MAAM,CAAC,QAAQ,CAAC,aAAa,CAAC,OAAO,CAAC,IAAI,EAAE,EAAE,CAAC,CAAC,KAAK,CAAC,GAAG,CAAC,CAAC,CAAC,CAAC,IAAI,EAAE,EAAE,EAAE,CAAC,CAAC;IACvF,OAAO,MAAM,CAAC,QAAQ,CAAC,KAAK,CAAC,IAAI,KAAK,IAAI,kBAAkB,CAAC;AAC/D,CAAC;AAED;;;GAGG;AACH,MAAM,UAAU,YAAY,CAAC,OAAe;IAC1C,OAAO,IAAI,GAAG,CAAC,cAAc,EAAE,OAAO,CAAC,CAAC;AAC1C,CAAC"}

package/dist/tui-launch.d.ts

@@ -0,0 +1,48 @@
+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. */
+    lab: string;
+    mode: "dry-run" | "live";
+    /** Injected in tests; defaults to the real spawn. */
+    spawn?: typeof spawn;
+    /** Injected in tests; defaults to the CLI beside this module. */
+    cliPath?: string;
+    env?: NodeJS.ProcessEnv;
+    /** Injected clock so a test can pin the log filename. */
+    now?: () => Date;
+}
+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
+     * 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.
+     */
+    launchedAt: string;
+    /** Absolute path to the launch log; the only diagnosis when a run dies before writing evidence. */
+    logPath: string;
+    /** Exactly what was executed, so a failure can be reproduced by hand. */
+    command: readonly string[];
+}
+export type LaunchRunResult = {
+    ok: true;
+    run: LaunchedRun;
+} | {
+    ok: false;
+    error: {
+        code: LaunchErrorCode;
+        message: string;
+    };
+};
+export type LaunchErrorCode = "HUMANISH_LAUNCH_INVALID_LAB" | "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. */
+export declare function readLaunchLogTail(logPath: string, maxBytes?: number): Promise<string>;

package/dist/tui-launch.js

@@ -0,0 +1,159 @@
+// Starting a run from the terminal surface (#455).
+//
+// 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
+// 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,
+// 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";
+import { open } from "node:fs/promises";
+import path from "node:path";
+import { fileURLToPath } from "node:url";
+import { prepareManagedHumanishOutputDirectory } from "./selected-output-paths.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
+ * 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.
+ */
+const SAFE_LAB_HANDLE = /^[A-Za-z0-9_][A-Za-z0-9._:-]*$/;
+export function isSafeLabHandle(value) {
+    return SAFE_LAB_HANDLE.test(value) && value.length <= 128;
+}
+/** Where the CLI lives, relative to this compiled module. */
+function defaultCliPath() {
+    return fileURLToPath(new URL("./cli.js", import.meta.url));
+}
+/**
+ * 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 async function launchRun(options) {
+    if (!isSafeLabHandle(options.lab)) {
+        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.`
+            }
+        };
+    }
+    const cwd = path.resolve(options.cwd);
+    const now = options.now ?? (() => new Date());
+    const spawnFn = options.spawn ?? spawn;
+    const launchedAt = now().toISOString();
+    let logPath;
+    let handle;
+    try {
+        // Contained under `.humanish/`, through the same guard every other output path uses, so a
+        // symlinked directory cannot redirect the log somewhere outside the project.
+        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
+        // 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);
+    }
+    catch (cause) {
+        return {
+            ok: false,
+            error: {
+                code: "HUMANISH_LAUNCH_FAILED",
+                message: `Could not open a launch log: ${cause instanceof Error ? cause.message : String(cause)}`
+            }
+        };
+    }
+    // `--json` because nothing reads this stream interactively; `--no-open` because the surface owns
+    // the operator's attention and must not have a browser thrown over it.
+    const args = [
+        options.cliPath ?? defaultCliPath(),
+        "lab",
+        "run",
+        "--cwd",
+        cwd,
+        "--json",
+        "--no-open",
+        ...(options.mode === "dry-run" ? ["--dry-run"] : []),
+        // `--` ends option parsing, so the handle can only ever be read as the positional argument.
+        "--",
+        options.lab
+    ];
+    const spawnOptions = {
+        cwd,
+        env: options.env ?? process.env,
+        // A new process group, so the SIGHUP that arrives when a terminal closes is not delivered here.
+        detached: true,
+        // stdin closed, output to the log: a detached process must never hold the terminal, and
+        // inheriting a pipe nobody reads is how a run blocks forever on a full buffer.
+        stdio: ["ignore", handle.fd, handle.fd]
+    };
+    try {
+        const child = spawnFn(process.execPath, args, spawnOptions);
+        // 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
+        // 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", () => {
+            // Deliberately empty: see above. The failure surfaces as a run that never reports in.
+        });
+        if (child.pid === undefined) {
+            await handle.close();
+            return {
+                ok: false,
+                error: { code: "HUMANISH_LAUNCH_FAILED", message: "The run process did not start." }
+            };
+        }
+        // Release the surface's hold: the parent can now exit whenever it likes and the run continues,
+        // reparented to init.
+        child.unref();
+        // The child owns the descriptor now.
+        await handle.close();
+        return {
+            ok: true,
+            run: { pid: child.pid, launchedAt, logPath, command: [process.execPath, ...args] }
+        };
+    }
+    catch (cause) {
+        await handle.close().catch(() => undefined);
+        return {
+            ok: false,
+            error: {
+                code: "HUMANISH_LAUNCH_FAILED",
+                message: cause instanceof Error ? cause.message : String(cause)
+            }
+        };
+    }
+}
+/** 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");
+        try {
+            const { size } = await handle.stat();
+            const start = Math.max(0, size - maxBytes);
+            const buffer = Buffer.alloc(Math.min(size, maxBytes));
+            await handle.read(buffer, 0, buffer.length, start);
+            return buffer.toString("utf8").trim();
+        }
+        finally {
+            await handle.close();
+        }
+    }
+    catch {
+        return "";
+    }
+}
+//# sourceMappingURL=tui-launch.js.map

package/dist/tui-launch.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"tui-launch.js","sourceRoot":"","sources":["../src/tui-launch.ts"],"names":[],"mappings":"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"}

package/docs/contracts/run-bundle.md

@@ -21,6 +21,10 @@ runId: "<core run id>"
 mode: "dry-run|live"
 simCount: 1
 createdAt: "<ISO timestamp>"
+lab: # optional, additive: which manifest produced this run
+  id: "<lab id>"
+  path: "humanish/labs/<lab id>.yaml"
+  origin: "committed|ignored|explicit"
 cwd: "[target-cwd]"
 artifactRoot: ".humanish/runs/<run-id>"
 source:
@@ -360,6 +364,10 @@ History entries use:
 schema: humanish.run-history-entry.v1
 runId: "<run-id>"
 createdAt: "<ISO timestamp>"
+lab: # optional, additive: which manifest produced this run
+  id: "<lab id>"
+  path: "humanish/labs/<lab id>.yaml"
+  origin: "committed|ignored|explicit"
 mode: "dry-run|live"
 path: ".humanish/runs/<run-id>"
 ```

package/docs/contracts/schemas.md

@@ -3,7 +3,7 @@
 Date: 2026-06-02 (current-state note updated 2026-07-14)
 
 Status: reference map for the major contracts shipped through source version
-`0.48.0`; it is not an exhaustive inventory of command/result envelopes. Exported types,
+`0.50.0`; it is not an exhaustive inventory of command/result envelopes. Exported types,
 schema constants, parsers, and validators in `src/` are authoritative. Rows
 marked "reserved" name layering intent only — no code emits or validates them
 yet. Do not emit a reserved schema.
@@ -371,6 +371,14 @@ Core-owned fields:
 - `artifacts`
 - `review`
 - `feedbackCandidates`
+- `lab` (optional, additive): which manifest produced the run —
+  `{ id, path?, origin? }`, where `origin` is `committed` (humanish/labs),
+  `ignored` (a local overlay), or `explicit` (a path the operator passed).
+  Absent on bundles written before this contract and on library callers who
+  hand a `LabConfig` directly — the run is then honestly lab-less rather than
+  guessed. Readers wanting attribution for an older bundle may fall back to
+  `inferLegacyLabId`, which reads only the historical
+  `persona.source = "lab:<id>"` convention and nothing else.
 - `subject` (optional, additive): structured subject provenance —
   `{ source: clone | app-url | local-tree, repo?, commit?, archiveSha256?,
   dirty?, envNames?, state }` where `state` is `{ provenance: seeded |
@@ -724,7 +732,11 @@ Core-owned fields:
   budget AFTER productive activity — status `passed`, a NON-FAILURE completion,
   distinct from `timed_out`, which stays reserved for a zero-progress deadline
   hit and remains a failure)
-- `ids`, `counts`, `items[]`, optional `tokenUsage`, `capabilities`. Items may
+- `ids`, `counts`, `items[]`, optional `tokenUsage`, `capabilities`. `tokenUsage`
+  may carry `cacheWriteInput` (tokens billed at the provider's cache-write rate,
+  OpenAI 5.6+) and `turns[]` (per provider-request usage, the recorded fact
+  long-context tier pricing needs) — both additive and honestly absent on
+  producers that do not report them (#334). Items may
   carry `at` (ISO-8601 recording stamp from the loop's clock) and, on
   click-like `ui_action` items, structured `coord` (`x`/`y`) — both additive
   (#441): absent on older bundles and non-stamping producers, and absence means
@@ -875,6 +887,67 @@ measure) and never grant a green pass (they surface as unmeasured). `verifyRun`
 fails closed when a live bundle lacks the cost ledger or no-spend proof, when the
 proof claims zero on a `null` line, or when known spend exceeds the declared cap.
 
+## Run Status (identity + liveness index)
+
+`humanish.run-status.v1` — `status.json`, written inside each run directory by
+every backend at run start, refreshed on a fixed cadence while the run is
+alive, and finalized when it ends: `{ schema, runId, state: running |
+finished, mode, lab?, pid, startedAt, updatedAt, completedAt?, outcome? }`.
+
+It answers two questions the filesystem could not answer before: **which lab**
+a run belongs to, and **whether it is still alive** — including for runs an
+agent launched (`lab run --json`) or that were detached, which previously wrote
+nothing at all until they completed.
+
+It is a DERIVED INDEX, not evidence. `run.json` remains the evidence-of-record;
+`verify` never gates on `status.json`, nothing in it is a claim about what a
+participant did, and when the two disagree the bundle wins and the record is
+rebuildable from it. A `running` record whose `updatedAt` is older than three
+touch intervals is INTERRUPTED, not alive — a dropped connection or a killed
+terminal leaves exactly that shape, and reading it as interrupted is the honest
+outcome (`classifyRunStatus` is the one shared definition). Fields are
+public-safe by construction: no hostname and no user paths, because a run
+directory may be shared.
+
+## Run Index, Run Detail, And The Terminal Surface (#455)
+
+Three derived projections that exist so a surface can list, classify and watch
+runs without opening evidence for all of them. None is authoritative: `run.json`
+remains the evidence-of-record, `verify` gates on none of these, and nothing in
+them is a claim about what a participant did.
+
+`humanish.run-index.v1` — the listing projection. One entry per run, read
+cheapest-source-first: the `status.json` record, else the bundle, else the run
+directory alone. `{ runId, derivedFrom: status | bundle | directory, liveness,
+mode?, pid?, lab?, startedAt?, updatedAt?, completedAt?, verdict?,
+participants?, estimatedCostUsd?, durationMs? }`. The point is cost: walking
+every run tree and parsing every bundle measured 167ms on a 25-run project,
+against 16ms cold and 2.8ms warm here, which is what makes a surface that
+refreshes on a cadence affordable. `derivedFrom` is reported so a surprising row
+can be traced to the file it came from. A run with receipts and no outcome is
+`interrupted` — the shape a dropped connection leaves — and so is an
+IN-PROGRESS bundle reached without a status record, because there is no
+freshness to judge and "it started and nothing here says it finished" is the
+honest reading.
+
+`humanish.run-detail.v1` — the watching projection, for ONE run. Who is in it
+and what they are thinking: `{ runId, participants: [{ id, label, personaId?,
+traits, status?, completionReason?, thought?, turns?, actions?, thoughts?,
+estimatedCostUsd? }], observerPath? }`. It reads the actor trace from
+`stream.liveActor` while a run is in flight and `stream.actor` once it has
+finished, preferring the live one, so a single screen renders a run the whole
+way through. A reasoning item still being written is skipped rather than quoted
+half-finished, and the text is carried verbatim — a surface may wrap it, nothing
+paraphrases it. Unlike the index this DOES open the bundle, which is affordable
+only because it is asked for the one run being watched.
+
+`humanish.tui-result.v1` — what `humanish tui` emits when it refuses:
+`{ schema, ok: false, error: { code, message } }` with `HUMANISH_TUI_REQUIRES_TTY`,
+`HUMANISH_TUI_UNSUPPORTED_NODE`, or `HUMANISH_TUI_BUNDLE_MISSING`. Every other
+command is built for an agent to drive; this one takes the screen and waits for
+a person, so a non-interactive stdin or stdout fails closed naming the commands
+that DO answer the question rather than rendering escape codes into a pipe.
+
 ## Run Cost Summary And Estimated Actor Cost
 
 The computer-use (CUA) lane surfaces an ADVISORY, additive cost ESTIMATE. It is
@@ -887,11 +960,16 @@ never authoritative: every dollar figure is a rate-table multiply, labeled
   dated per-model input/output USD-per-token rates and an E2B desktop
   USD-per-minute rate, each with a public pricing-page `source` and an `asOf`
   date. A prominent banner says these are estimates to update when providers
-  change pricing. Some entries are `placeholder: true` stand-ins (the shipped
-  `gpt-5.5` model rate and the E2B desktop rate) — an operator MUST confirm them
-  before trusting the magnitude; the flag propagates into every estimate so a
-  stand-in is never mistaken for a live rate. An UNKNOWN model/desktop rate is
-  DECLARED ABSENT (`estimatedCostUsd: null` + a `reason`), never guessed.
+  change pricing. Model rates may carry a `cacheWriteUsdPerToken` (OpenAI 5.6+
+  bills cache writes at 1.25x input as the total rate for written tokens) and a
+  `longContext` tier (a per-request input threshold that re-prices the whole
+  request; priced exactly only from the trace's per-request `turns` ledger —
+  totals alone never re-tier, which is the under-estimate direction). Some
+  entries are `placeholder: true` stand-ins (the E2B desktop rate, pending a
+  live RAM-spec confirmation) — an operator MUST confirm them before trusting
+  the magnitude; the flag propagates into every estimate so a stand-in is never
+  mistaken for a live rate. An UNKNOWN model/desktop rate is DECLARED ABSENT
+  (`estimatedCostUsd: null` + a `reason`), never guessed.
 - `humanish.actor-estimated-cost.v1` — `ActorTrace.estimatedCost`: one lane's
   token-derived model cost, with `estimatedCostUsd` (or `null` + `reason`
   `no_rate_for_model`/`no_token_usage`), `ratesAsOf`, `source`, `modelId`,

package/docs/goals/current.md

@@ -29,7 +29,7 @@ study completed, reproduced, and produced a real accessibility finding via a
 keyboard-first participant
 ([docs/goals/email-gated-signup/receipts/](email-gated-signup/receipts/)).
 
-## Current Program Truth (source `0.48.0`)
+## Current Program Truth (source `0.50.0`)
 
 The package source and repository implementation in this tree agree on these
 points:
@@ -45,7 +45,8 @@ The immutable 2026-06-10 proof-roadmap packet is paired with a
 | Subject sources/routes | Six declared sources: `this-repo`, `clone`, `app-url`, `local-app`, `terminal-product`, and `local-tree`; support is route-specific and `this-repo` remains dry-run-only | One centralized run/resource lifecycle boundary across all routes |
 | Public proof | A legible four-persona Observer hero from a verified real public-application study (commit-pinned drawDB) shipped in the npm payload (`0.16.0`) | Coverage beyond a single studied subject; the stratified breadth panel remains unbuilt |
 | OSS meta-lab | Dry-run contract and separate disposable smoke harness | Live meta-lab execution; disabled until repository instructions and actor credentials have an isolated boundary |
-| Observer serving | `watch`/`observe` loopback servers plus `serve` — the run-library surface with loopback default, capability-link exposure, `share_ready`-gated open mode, and optional operator-run tunnel; streams never served remotely | A remote live-stream (`--live-streams`) design; a persistent capability-link store; a control plane that can start runs |
+| Observer serving | `watch`/`observe` loopback servers plus `serve` — the run-library surface with loopback default, capability-link exposure, `share_ready`-gated open mode, and optional operator-run tunnel; streams never served remotely | A remote live-stream (`--live-streams`) design; a persistent capability-link store |
+| Stakeholder terminal surface | `humanish tui` (`0.50.0`): labs -> lab -> run, arrow-key navigation, and starting a dry or live run from the lab screen. The run is DETACHED and outlives the terminal — live-proven by killing the terminal 42s into a real run that then ran on for ~3.5 minutes and finished `pass` at $0.639751. The run screen leads with the participant and their recorded thinking, live-proven mid-flight against a real computer-use run. Ships as one bundled file loaded on demand; refuses a non-interactive stdin/stdout naming the JSON commands instead | Cancelling a run from the surface; per-user persisted config (#470); export (#471); aggregate stats (#472); agent-authored labs (#473); a reusable persona panel (#474) |
 | Off-app comms | Vendor-neutral in-sandbox email/SMS catch, a minimal persona inbox surface, and digest-only `humanish.comms-thread.v1` evidence; wired into the computer-use and shared-world routes over both HTTP and SMTP; live-proven end to end on 2026-08-08 — a persona signed up for a public app, read the emailed link in its inbox, and reached the signed-in product (`docs/goals/email-gated-signup/receipts/signup-verify-live-2026-08-08.md`); the adopter-hosted / app-url ingress plane is wired on the CUA and concurrent external-public routes (#387/#380, 2026-08-11) | Real-provider delivery; a live adopter-hosted receipt |
 
 Capability proof and adopter replacement are different gates. A deterministic
@@ -487,17 +488,25 @@ Deep links landed in `0.48.0` (#464): every participant and frame is
 addressable (`#/lane/<id>/f/<n>`), Back/Forward restore the view, and a
 reload or shared link lands on the exact moment — #441 closed entirely.
 
+The npx-first-try adoption cluster closed in `0.49.0`, operator-prompted and
+adversarially red-teamed before merge (both arcs): provider keys now resolve
+through each vendor's native chain (#436 — the documented project overlay,
+`e2b auth login`'s store, `gh auth token`, and a `humanish keys set` user
+store; fills announced by name and source, never value; `HUMANISH_STRICT_KEYS=1`
+opts out) and #346 closed on its receipts. The computer-use default moved to
+`gpt-5.6-sol` with the whole 5.6 family priced, and the cost estimate now
+models the two billing mechanics 5.6 introduced — cache writes at 1.25x and
+long-context re-tiering — exactly, from a new per-request usage ledger on the
+trace (#334). Both spend caps price through the same tier-aware estimator.
+
 The standing queue, in rough order:
 
 1. registry promotions: the wordmark (#431), the participant card, and the two
    vendored Base UI wrappers (drawer, popover) once a second surface consumes
    them;
-2. the adoption cluster: vendor-native key resolution (#436) and the optional
-   desktop peer-dep gap (#346) — the two biggest remaining "npx works
-   first-try" violations;
-3. shared-world honesty, remaining half: per-action evidence (#365) and
+2. shared-world honesty, remaining half: per-action evidence (#365) and
    exposure-flag coverage (#446);
-4. the stakeholder TUI (#455): research + token-translated mocks on the
+3. the stakeholder TUI (#455): research + token-translated mocks on the
    operator review surface, design sign-off gated before any code.
 
 The depth-axis deletion front (an adopter's bespoke terminal-product sim,

package/docs/ramp/README.md

@@ -2,7 +2,7 @@
 
 Status: public-safe contributor and agent ramp.
 
-Package/source version in this tree: `0.48.0` (2026-08-17). The Observer is phone-usable as a stated requirement (observer/AGENTS.md); interactive primitives start from Base UI. The Observer renderer is the observer/ workspace artifact only; the legacy string-concat renderer was deleted at cutover (#426), and rollback is a version pin to 0.42.0. The containment boundary introduced in
+Package/source version in this tree: `0.50.0` (2026-08-20). The Observer is phone-usable as a stated requirement (observer/AGENTS.md); interactive primitives start from Base UI. The Observer renderer is the observer/ workspace artifact only; the legacy string-concat renderer was deleted at cutover (#426), and rollback is a version pin to 0.42.0. The containment boundary introduced in
 `0.15.1` remains in force: managed run and output paths bind to validated
 physical filesystem identities, and stored provider IDs are evidence, not
 cleanup authority. The bundled OSS meta-lab is dry-run only until

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "humanish",
-  "version": "0.48.0",
+  "version": "0.50.0",
   "description": "Open-source-safe CLI for persona simulation, observer review, and public-safe feedback drafts.",
   "author": "Daniel G Wilson <daniel@danielgwilson.com>",
   "keywords": [
@@ -49,8 +49,8 @@
     "access": "public"
   },
   "scripts": {
-    "build": "tsc -p tsconfig.build.json && pnpm --filter humanish-observer build && node --eval \"import('node:fs').then(({ chmodSync, copyFileSync }) => { chmodSync('dist/cli.js', 0o755); copyFileSync('observer/dist/index.html', 'dist/observer-app.html'); })\"",
-    "check": "pnpm typecheck && pnpm test && pnpm build",
+    "build": "tsc -p tsconfig.build.json && pnpm --filter humanish-observer build && pnpm --filter humanish-tui build && node scripts/finish-build.mjs",
+    "check": "pnpm typecheck && pnpm test && pnpm tui:test && pnpm build && pnpm tui:smoke",
     "humanish": "tsx src/cli.ts",
     "pack:dry-run": "npm pack --dry-run",
     "prepack": "pnpm build",
@@ -58,7 +58,7 @@
     "release:check": "pnpm check && pnpm public-surface:scan && pnpm skill:check && npm pack --dry-run",
     "skill:check": "DISABLE_TELEMETRY=1 npx skills add . --list",
     "test": "vitest run",
-    "typecheck": "tsc -p tsconfig.json --noEmit && pnpm --filter humanish-observer typecheck",
+    "typecheck": "tsc -p tsconfig.json --noEmit && pnpm --filter humanish-observer typecheck && pnpm --filter humanish-tui typecheck",
     "humanish:doctor": "pnpm humanish -- doctor",
     "humanish:run": "pnpm humanish -- run --dry-run",
     "humanish:watch": "pnpm humanish -- watch",
@@ -69,7 +69,10 @@
     "humanish:lab:list": "pnpm humanish -- lab list",
     "humanish:lab:oss": "pnpm humanish -- lab run oss",
     "humanish:lab:oss:ci": "pnpm humanish -- lab run oss --dry-run --json --no-open",
-    "humanish:lab:oss:smoke": "pnpm humanish -- lab run oss-smoke"
+    "humanish:lab:oss:smoke": "pnpm humanish -- lab run oss-smoke",
+    "tui:typecheck": "pnpm --filter humanish-tui typecheck",
+    "tui:smoke": "node scripts/tui-smoke.mjs",
+    "tui:test": "pnpm --filter humanish-tui test"
   },
   "repository": {
     "type": "git",

package/skills/humanish/SKILL.md

@@ -21,6 +21,25 @@ assume broad inherited job env is safe. Stop before live provider spend,
 hosted execution, deploys, public tunnels, or GitHub mutation unless the user
 explicitly approves that exact action.
 
+## Not For You: `humanish tui`
+
+`humanish tui` is a human-only surface. It takes over the terminal and waits for
+keystrokes, so it will block you and produce nothing you can read. It refuses a
+non-interactive stdin or stdout with `HUMANISH_TUI_REQUIRES_TTY` rather than
+rendering escape codes into your transcript — but do not invoke it at all.
+
+Everything it shows has a machine-readable equivalent, which is what you want:
+
+| Instead of the TUI | Use |
+| --- | --- |
+| browsing labs | `npx humanish lab list --json` |
+| browsing runs | `npx humanish runs --json` |
+| starting a run | `npx humanish lab run <lab> --json --no-open` |
+| a run's outcome | `npx humanish review --run <id> --json` |
+
+If a human asks you to "open the TUI", tell them the command to type; do not run
+it on their behalf.
+
 ## Setup Workflow
 
 1. Inspect public target-repo files only: `package.json`, docs, route/app