humanish 0.105.0 → 0.106.0

package/dist/tui/actions.js

@@ -0,0 +1,203 @@
+import { requestAutomaticStudyAnalysisCancellation } from "../analysis/automatic.js";
+// The two things a run card can DO (#455 rev 8).
+//
+// 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
+// control that fails.
+import { readFile } from "node:fs/promises";
+import path from "node:path";
+import { RUN_STATUS_FILE, isRunStatusRecord } from "../run/status.js";
+import { resolveRunPath } from "../run/locate.js";
+import { bindExistingRunArtifactPaths, isSafeRunIdSegment } from "../run/paths.js";
+import { openTarget } from "../observer/render.js";
+import { serveObserverLibrary } from "../observer/serve.js";
+export const TUI_ACTION_SCHEMA = "humanish.tui-action.v1";
+/**
+ * The library server projects the latest contained bundle on each browser poll. It can follow
+ * captures written by another process without starting a study or recovering desktop credentials.
+ * Keeping it in this process avoids detached viewers accumulating each time Open Observer is used.
+ */
+export function createTuiObserverSession(cwdInput, options = {}) {
+    const cwd = path.resolve(cwdInput);
+    const open = options.openTarget ?? openTarget;
+    let serverPromise;
+    let closed = false;
+    let closePromise;
+    const result = (ok, message) => ({
+        schema: TUI_ACTION_SCHEMA,
+        ok,
+        message,
+    });
+    return {
+        async open(targetCwd, observerPath) {
+            if (closed)
+                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.
+            // Validate the exact shape before using its id, then enforce the existing physical storage
+            // boundary (including descendant symlinks). An index.html need not exist during an active
+            // run: the HTTP server renders it from the contained run.json or observer-data.json.
+            const relative = path.relative(cwd, path.resolve(cwd, observerPath));
+            const segments = relative.split(path.sep);
+            const runId = segments[2];
+            if (segments.length !== 5 ||
+                segments[0] !== ".humanish" ||
+                segments[1] !== "runs" ||
+                !runId ||
+                !isSafeRunIdSegment(runId) ||
+                segments[3] !== "observer" ||
+                segments[4] !== "index.html") {
+                return result(false, "Observer requires a run under this project's .humanish/runs directory");
+            }
+            try {
+                await bindExistingRunArtifactPaths(cwd, runId);
+            }
+            catch {
+                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");
+            try {
+                // Share the pending start too: two quick selections must not create two listeners.
+                serverPromise ??= serveObserverLibrary(cwd, {
+                    port: 0,
+                    safe: false,
+                    expose: false,
+                    edgeAuthed: false,
+                })
+                    .then((started) => {
+                    if (!started.ok)
+                        throw new Error(started.error.message);
+                    return started.server;
+                })
+                    .catch((error) => {
+                    serverPromise = undefined;
+                    throw error;
+                });
+                const server = await serverPromise;
+                if (closed)
+                    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."}`);
+            }
+            catch {
+                return result(false, "Observer could not start — try humanish observe --run with this run's id in another terminal");
+            }
+        },
+        close() {
+            closed = true;
+            closePromise ??= (async () => {
+                // A close racing startup still awaits and releases the listener it owns.
+                const server = await serverPromise?.catch(() => undefined);
+                await server?.close();
+            })();
+            return closePromise;
+        },
+    };
+}
+/**
+ * Stop a run that is still going.
+ *
+ * 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
+ * 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.
+ *
+ * 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.
+ */
+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);
+        return {
+            schema: TUI_ACTION_SCHEMA,
+            ok: analysis.requested,
+            message: analysis.requested
+                ? "asked analysis to cancel; no participant process was signalled"
+                : "analysis is not available for cancellation; no participant process was signalled",
+        };
+    }
+    if (intent !== "run")
+        return { schema: TUI_ACTION_SCHEMA, ok: false, message: "unknown stop action" };
+    const runPaths = await resolveRunPath(path.resolve(cwd), runId).catch(() => null);
+    if (runPaths === null) {
+        return { schema: TUI_ACTION_SCHEMA, ok: false, message: `no run directory for ${runId}` };
+    }
+    let record;
+    try {
+        record = JSON.parse(await readFile(path.join(runPaths.absoluteRunRoot, RUN_STATUS_FILE), "utf8"));
+    }
+    catch {
+        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",
+        };
+    }
+    if (!isRunStatusRecord(record)) {
+        return {
+            schema: TUI_ACTION_SCHEMA,
+            ok: false,
+            message: "this run's status record is unreadable",
+        };
+    }
+    if (record.state === "finished") {
+        const analysis = await requestAutomaticStudyAnalysisCancellation(cwd, runId);
+        if (analysis.requested)
+            return {
+                schema: TUI_ACTION_SCHEMA,
+                ok: true,
+                message: "asked analysis to cancel; the participant recording is already finished",
+            };
+        return { schema: TUI_ACTION_SCHEMA, ok: false, message: "this run already finished" };
+    }
+    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.
+    try {
+        process.kill(pid, 0);
+    }
+    catch {
+        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`,
+        };
+    }
+    try {
+        // Negative pid = the whole process group, which is why the run was spawned detached.
+        process.kill(-pid, "SIGTERM");
+    }
+    catch {
+        try {
+            process.kill(pid, "SIGTERM");
+        }
+        catch (cause) {
+            return {
+                schema: TUI_ACTION_SCHEMA,
+                ok: false,
+                message: `could not stop it: ${cause instanceof Error ? cause.message : String(cause)}`,
+            };
+        }
+    }
+    return {
+        schema: TUI_ACTION_SCHEMA,
+        ok: true,
+        message: "asked the run to stop — its sandboxes are separate, so Reclaim them once it reports interrupted",
+    };
+}

package/dist/tui/contract.d.ts

@@ -0,0 +1,144 @@
+import type { LabListResult } from "../lab/discover.js";
+import type { LabSummary, ReadLabSummaryOptions } from "../lab/summary.js";
+import type { RunDetail } from "../run/detail.js";
+import type { ReclaimResult } from "../run/reclaim.js";
+import type { TuiActionResult } from "./actions.js";
+import type { TuiProjectState } from "./project.js";
+import type { ReadRunIndexOptions, RunIndexResult } from "../run/run-index.js";
+import type { LaunchRunOptions, LaunchRunResult } from "./launch.js";
+import type { CommsSetupResult } from "../comms/connections.js";
+import type { CommsSetupStatus } from "../comms/setup.js";
+import type { CommsCheckResult, CommsConfigureResult } from "../comms/setup.js";
+import type { CommsRecoveryEntry } from "../comms/lease-store.js";
+/** The humanish version string shown in the frame, so a screenshot in a bug report is datable. */
+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 {
+    /** Optional for older embedders. Credentials are never returned to the view. */
+    comms?: {
+        read(): Promise<CommsSetupStatus>;
+        save(): Promise<CommsSetupResult>;
+        check?(): Promise<CommsCheckResult>;
+        labs?(): Promise<{
+            title: string;
+            path: string;
+        }[]>;
+        configure?(lab: string, apply: boolean, planToken?: string): Promise<CommsConfigureResult>;
+        recovery?(): Promise<CommsRecoveryEntry[]>;
+        recover?(runId: string, connectionName: string): Promise<{
+            ok: boolean;
+            message: string;
+        }>;
+    };
+    /** 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>;
+    /**
+     * 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
+     *  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. */
+    openObserver(cwd: string, observerPath: string): Promise<TuiActionResult>;
+    /** 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. */
+    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).
+     */
+    initProject(cwd: string): Promise<TuiActionResult>;
+}
+export interface TuiOptions {
+    /** Return to setup after the host-owned hidden prompt has finished. */
+    initialScreen?: "connections";
+    connectionNotice?: string;
+    /** 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 TuiHandoff = {
+    action: "agentmail-key";
+};
+export type StartTui = (options: TuiOptions) => Promise<number | TuiHandoff>;
+/** The shape `dist/tui-app.js` exports. Asserted at the load boundary in cli/commands/tui.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;
+/**
+ * The shipped bundle, dist/tui-app.js, one level above this module (dist/tui/contract.js). The
+ * command that loads it and the readiness row that reports it both read this constant, so moving
+ * either caller cannot change where they look. scripts/tui-smoke.mjs checks it against the build.
+ */
+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.
+ *
+ * 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
+ * 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
+ * as "not for you" and dies in the transcript.
+ */
+export declare function terminalSurfaceMessage(state: {
+    supported: boolean;
+    bundlePresent: boolean;
+    interactive: boolean;
+    nodeVersion: string;
+}): string;
+export {};

package/dist/tui/contract.js

@@ -0,0 +1,52 @@
+// 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;
+}
+/**
+ * The shipped bundle, dist/tui-app.js, one level above this module (dist/tui/contract.js). The
+ * command that loads it and the readiness row that reports it both read this constant, so moving
+ * either caller cannot change where they look. scripts/tui-smoke.mjs checks it against the build.
+ */
+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.
+ *
+ * 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
+ * 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
+ * as "not for you" and dies in the transcript.
+ */
+export function terminalSurfaceMessage(state) {
+    if (!state.supported) {
+        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 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";
+}

package/dist/tui/launch.js

@@ -0,0 +1,172 @@
+// 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 { 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
+ * 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);
+    let selectedLab = options.lab;
+    if (options.manifestPath !== undefined) {
+        const resolved = await resolveLabManifest(cwd, options.manifestPath);
+        if (!resolved.ok)
+            return {
+                ok: false,
+                error: {
+                    code: "HUMANISH_LAUNCH_INVALID_LAB",
+                    message: "The selected lab path could not be read safely. Refresh the lab list.",
+                },
+            };
+        selectedLab = path.relative(cwd, path.resolve(cwd, resolved.path)).replace(/\\/g, "/");
+    }
+    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.
+        "--",
+        selectedLab,
+    ];
+    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 "";
+    }
+}

package/dist/tui/project.d.ts

@@ -0,0 +1,10 @@
+declare const TUI_PROJECT_SCHEMA = "humanish.tui-project.v1";
+export interface TuiProjectState {
+    schema: typeof TUI_PROJECT_SCHEMA;
+    /** A committed `humanish/` source directory: this project has been `init`-ed. */
+    initialized: boolean;
+    /** A `.humanish/` runtime directory: something has been run here, even if source is absent. */
+    hasRuntime: boolean;
+}
+export declare function readProjectState(cwdInput: string): TuiProjectState;
+export {};

package/dist/tui/project.js

@@ -0,0 +1,17 @@
+// Is this directory a humanish project at all? (#455)
+//
+// 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.
+import { existsSync } from "node:fs";
+import path from "node:path";
+const TUI_PROJECT_SCHEMA = "humanish.tui-project.v1";
+export function readProjectState(cwdInput) {
+    const cwd = path.resolve(cwdInput);
+    return {
+        schema: TUI_PROJECT_SCHEMA,
+        initialized: existsSync(path.join(cwd, "humanish")),
+        hasRuntime: existsSync(path.join(cwd, ".humanish")),
+    };
+}