humanish 0.104.3 → 0.106.0

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

@@ -0,0 +1,143 @@
+import { execFile } from "node:child_process";
+import { mkdtemp, rm, writeFile } from "node:fs/promises";
+import { tmpdir } from "node:os";
+import path from "node:path";
+import { promisify } from "node:util";
+const exec = promisify(execFile);
+export const LIMA_INSTANCE = "humanish-runtime";
+export const usesLima = (options = {}) => (options.platform ?? process.platform) === "darwin";
+export function runtimeArchitecture(options = {}) {
+    const platform = options.platform ?? process.platform, arch = options.arch ?? process.arch;
+    if (platform === "linux" && arch === "x64")
+        return "amd64";
+    // The arm64 image runs in the Mac's Lima guest. A native Linux ARM64 host is refused: the local
+    // participant (the restricted Codex participant) runs only on Linux x64 and Apple-silicon macOS.
+    if (platform === "darwin" && arch === "arm64")
+        return "arm64";
+    return undefined;
+}
+export async function hostExec(file, args, options = {}, timeout = 15_000) {
+    return exec(file, args, {
+        env: options.env ?? process.env,
+        timeout,
+        maxBuffer: 1024 * 1024,
+        ...(options.signal ? { signal: options.signal } : {}),
+    });
+}
+/** Commands inside the Linux host. Lima carries argv; no shell interpolation. */
+export async function runtimeExec(file, args, options = {}, timeout = 15_000) {
+    return usesLima(options)
+        ? hostExec("limactl", ["shell", "--workdir", "/", LIMA_INSTANCE, "--", file, ...args], options, timeout)
+        : hostExec(file, args, options, timeout);
+}
+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)
+        : runtimeExec("docker", args, options, timeout);
+}
+// No host mounts, agent forwarding or automatic app-port discovery. Per-study
+// OpenSSH forwards grant just the selected app and browser-control sockets.
+const LIMA_TEMPLATE = `minimumLimaVersion: 2.2.0
+vmType: vz
+arch: aarch64
+nestedVirtualization: true
+cpus: 6
+memory: 8GiB
+disk: 80GiB
+images:
+  - location: https://cloud.debian.org/images/cloud/trixie/20260712-2537/debian-13-genericcloud-arm64-20260712-2537.qcow2
+    arch: aarch64
+    digest: sha512:8543d795f2fde630eb66c492f245a8c1da19dedc636e0a8e7b3d0f95920e1a05aa911ef2d82d177d41cc53ced5fccbd2a3945d07fa5e15018914c4d864bb07ed
+mounts: []
+containerd:
+  system: false
+  user: false
+ssh:
+  forwardAgent: false
+portForwards:
+  - guestIP: 0.0.0.0
+    guestIPMustBeZero: false
+    guestPortRange: [1, 65535]
+    proto: any
+    ignore: true
+provision:
+  - mode: system
+    script: |
+      #!/bin/sh
+      set -eu
+      export DEBIAN_FRONTEND=noninteractive
+      apt-get update
+      apt-get install -y --no-install-recommends docker.io docker-cli ca-certificates
+      systemctl enable --now docker
+`;
+export async function limaStatus(options = {}) {
+    const chip = (await hostExec("sysctl", ["-n", "machdep.cpu.brand_string"], options)).stdout.trim();
+    const generation = /^Apple M(\d+)/.exec(chip);
+    if (!generation || Number(generation[1]) < 3)
+        throw new Error("Local Firecracker on Mac requires an M3 or newer Apple Silicon Mac with nested virtualization.");
+    let version;
+    try {
+        version = (await hostExec("limactl", ["--version"], options)).stdout;
+    }
+    catch {
+        throw new Error("Install Lima 2.2 or newer (brew install lima), then run humanish runtime setup. Docker Desktop is not required.");
+    }
+    const match = /\b(\d+)\.(\d+)\.\d+/.exec(version);
+    if (!match || Number(match[1]) < 2 || (Number(match[1]) === 2 && Number(match[2]) < 2))
+        throw new Error("Update Lima to 2.2 or newer (brew upgrade lima), then run humanish runtime setup.");
+    const output = (await hostExec("limactl", ["list", "--json"], options)).stdout.trim();
+    const instance = output
+        .split("\n")
+        .filter(Boolean)
+        .map((line) => JSON.parse(line))
+        .find((value) => value.name === LIMA_INSTANCE);
+    if (instance &&
+        (instance.name !== LIMA_INSTANCE || instance.vmType !== "vz" || instance.arch !== "aarch64"))
+        throw new Error(`The existing ${LIMA_INSTANCE} Lima instance is incompatible. humanish will not replace it.`);
+    return {
+        ready: instance?.status === "Running",
+        exists: !!instance,
+        message: instance
+            ? "The humanish Lima host is stopped. Run humanish runtime setup to start it."
+            : "Run humanish runtime setup to create the humanish Lima host and install the browser runtime.",
+    };
+}
+export async function prepareLima(options = {}, progress) {
+    const status = await limaStatus(options);
+    if (status.ready)
+        return;
+    progress?.(status.exists
+        ? "Starting the humanish Lima host…"
+        : "Preparing the humanish Lima host (first setup downloads Linux and Docker)…");
+    if (status.exists) {
+        await hostExec("limactl", ["start", "--tty=false", LIMA_INSTANCE], options, 15 * 60_000);
+    }
+    else {
+        const work = await mkdtemp(path.join(tmpdir(), "humanish-lima-"));
+        try {
+            const file = path.join(work, "host.yaml");
+            await writeFile(file, LIMA_TEMPLATE, { mode: 0o600 });
+            await hostExec("limactl", ["start", "--tty=false", "--name", LIMA_INSTANCE, file], options, 15 * 60_000);
+        }
+        finally {
+            await rm(work, { recursive: true, force: true });
+        }
+    }
+}
+/** Copy across the OS boundary explicitly; shared folders cannot carry sockets. */
+export async function loadRuntimeArchive(archive, options) {
+    if (!usesLima(options)) {
+        await runtimeDocker(["load", "--input", archive], options, 10 * 60_000);
+        return;
+    }
+    const work = (await runtimeExec("mktemp", ["-d", "/tmp/humanish-image-XXXXXX"], options)).stdout.trim();
+    try {
+        await hostExec("limactl", ["copy", archive, `${LIMA_INSTANCE}:${work}/runtime.tar.gz`], options, 10 * 60_000);
+        await runtimeDocker(["load", "--input", `${work}/runtime.tar.gz`], options, 10 * 60_000);
+    }
+    finally {
+        // Cancellation must not skip removal of this invocation's copied archive.
+        const { signal: _signal, ...cleanup } = options;
+        await runtimeExec("rm", ["-rf", "--", work], cleanup);
+    }
+}

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

@@ -0,0 +1,5 @@
+import type { LocalRuntimeRelease } from "./runtime.js";
+/** Architecture-specific artifacts; each retains matching sources and notices. */
+export declare const LOCAL_RUNTIME_RELEASES: Partial<Record<"amd64" | "arm64", LocalRuntimeRelease>>;
+/** Media assets are separate so ordinary browser studies keep the smaller download. */
+export declare const LOCAL_MEDIA_RUNTIME_RELEASES: Partial<Record<"amd64" | "arm64", LocalRuntimeRelease>>;

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

@@ -0,0 +1,32 @@
+/** Updated with the verified, public runtime artifact before release. */
+const LOCAL_RUNTIME_RELEASE = {
+    url: "https://github.com/danielgwilson/humanish/releases/download/runtime-2026.09.28.1/runtime-linux-amd64.tar.gz",
+    sha256: "224be52467d6a808c79f156c6537d8a34c2dfb7b71daa836d34c8611fbbb6647",
+    bytes: 596142100,
+    image: "sha256:89cec77ea8097d32f3ef14bf2bdb0a93ffd25c3975913f8c5ffc6a2f360482a2",
+};
+/** Architecture-specific artifacts; each retains matching sources and notices. */
+export const LOCAL_RUNTIME_RELEASES = {
+    amd64: LOCAL_RUNTIME_RELEASE,
+    arm64: {
+        url: "https://github.com/danielgwilson/humanish/releases/download/runtime-2026.09.28.2/runtime-linux-arm64.tar.gz",
+        sha256: "d03e1b6335bea76a22bf88ca9aa8dc1f4fe0af16fba02c654a333766e27cd2ea",
+        bytes: 582661785,
+        image: "sha256:c3d584d9586d2e86833ee8d050c43774d456c6c4f8f3c9a53194bd90910fa938",
+    },
+};
+/** Media assets are separate so ordinary browser studies keep the smaller download. */
+export const LOCAL_MEDIA_RUNTIME_RELEASES = {
+    amd64: {
+        url: "https://github.com/danielgwilson/humanish/releases/download/runtime-2026.09.28.7/runtime-linux-amd64.tar.gz",
+        sha256: "f4758b39cb26c819c7f952eb329d5096fcfe9f05f7381bd37d205b2f6e51826c",
+        bytes: 846986597,
+        image: "sha256:91b132c72cdcb750fba3b48ee78ea8087c794d515d970a273b6f5ee22d443b9f",
+    },
+    arm64: {
+        url: "https://github.com/danielgwilson/humanish/releases/download/runtime-2026.09.28.8/runtime-linux-arm64.tar.gz",
+        sha256: "77f65fd945b582067cfde7740c26f4c06c2727afffcb0025720652c168377a01",
+        bytes: 828200616,
+        image: "sha256:68dd2c00f713bd8be03e209011531bbd4da5b840819cd2de203c11ece29aa255",
+    },
+};

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

@@ -0,0 +1,9 @@
+export declare function openLimaTunnel(options: {
+    work: string;
+    socketRoot: string;
+    appUrl: URL;
+    inboxUrl?: URL;
+    signal: AbortSignal;
+}): Promise<{
+    close(): Promise<boolean>;
+}>;

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

@@ -0,0 +1,129 @@
+import { spawn } from "node:child_process";
+import path from "node:path";
+import { setTimeout as delay } from "node:timers/promises";
+import { hostExec, LIMA_INSTANCE } from "./runtime-host.js";
+/** Standard OpenSSH streamlocal forwarding; no browser-control protocol here. */
+async function openRuntimeSshTunnel(options) {
+    options.signal.throwIfAborted();
+    const child = spawn("ssh", [
+        "-F",
+        options.config,
+        "-T",
+        "-a",
+        "-o",
+        "BatchMode=yes",
+        "-o",
+        "ControlMaster=no",
+        "-o",
+        "ControlPath=none",
+        "-o",
+        "ExitOnForwardFailure=yes",
+        "-o",
+        "ConnectTimeout=15",
+        "-o",
+        "StreamLocalBindMask=0177",
+        "-L",
+        `${options.localSocket}:${options.remoteSocket}`,
+        "-R",
+        `${options.appSocket}:${options.appHost}:${options.appPort}`,
+        ...(options.inbox
+            ? ["-R", `${options.inbox.socket}:${options.inbox.host}:${options.inbox.port}`]
+            : []),
+        options.destination,
+        "sh -c 'printf \"HUMANISH_SSH_READY\\n\"; exec cat'",
+    ], { stdio: ["pipe", "pipe", "pipe"] });
+    let exited = false;
+    const closed = new Promise((resolve) => child.once("close", () => {
+        exited = true;
+        resolve();
+    }));
+    child.stdin.on("error", () => { });
+    let closing;
+    const close = () => (closing ??= (async () => {
+        options.signal.removeEventListener("abort", aborted);
+        // EOF also closes the remote cat if the parent dies unexpectedly. Do not
+        // detach/multiplex this SSH child into Lima's persistent control connection.
+        child.stdin.end();
+        await Promise.race([closed, delay(1000)]);
+        if (!exited)
+            child.kill("SIGTERM");
+        await Promise.race([closed, delay(1000)]);
+        if (!exited)
+            child.kill("SIGKILL");
+        await Promise.race([closed, delay(1000)]);
+        return exited;
+    })());
+    const aborted = () => {
+        void close();
+    };
+    options.signal.addEventListener("abort", aborted, { once: true });
+    try {
+        await new Promise((resolve, reject) => {
+            const timer = setTimeout(() => finish(new Error("Lima SSH forwarding timed out.")), 20_000);
+            let bytes = 0, output = "", ready = false;
+            const finish = (error) => {
+                if (ready)
+                    return;
+                ready = true;
+                clearTimeout(timer);
+                if (error)
+                    reject(error);
+                else
+                    resolve();
+            };
+            child.once("error", () => finish(new Error("Could not start SSH for the Lima browser.")));
+            child.once("close", () => finish(new Error("Lima SSH forwarding closed before it was ready.")));
+            child.stderr.on("data", (data) => {
+                bytes += data.length;
+                if (bytes > 64 * 1024) {
+                    finish(new Error("Lima SSH forwarding failed."));
+                    void close();
+                }
+            });
+            child.stdout.on("data", (data) => {
+                bytes += data.length;
+                if (bytes > 64 * 1024) {
+                    finish(new Error("Lima SSH forwarding failed."));
+                    void close();
+                    return;
+                }
+                if (!ready) {
+                    output += data.toString();
+                    if (output === "HUMANISH_SSH_READY\n")
+                        finish();
+                }
+            });
+        });
+        options.signal.throwIfAborted();
+        return { close };
+    }
+    catch (error) {
+        await close();
+        throw error;
+    }
+}
+export async function openLimaTunnel(options) {
+    const settings = await hostExec("limactl", ["list", "--format={{.SSHConfigFile}}", LIMA_INSTANCE], { signal: options.signal });
+    const config = settings.stdout.trim();
+    if (!path.isAbsolute(config))
+        throw new Error("Lima did not return its SSH configuration path.");
+    return openRuntimeSshTunnel({
+        config,
+        destination: `lima-${LIMA_INSTANCE}`,
+        localSocket: path.join(options.work, "vsock.sock"),
+        remoteSocket: `${options.socketRoot}/vsock.sock`,
+        appSocket: `${options.socketRoot}/vsock.sock_8000`,
+        appHost: options.appUrl.hostname,
+        ...(options.inboxUrl
+            ? {
+                inbox: {
+                    socket: `${options.socketRoot}/vsock.sock_8001`,
+                    host: options.inboxUrl.hostname,
+                    port: Number(options.inboxUrl.port),
+                },
+            }
+            : {}),
+        appPort: Number(options.appUrl.port),
+        signal: options.signal,
+    });
+}

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

@@ -0,0 +1,25 @@
+import type { LocalFirecrackerAssets } from "./firecracker-desktop.js";
+import { type RuntimeHostOptions } from "./runtime-host.js";
+export interface LocalRuntimeRelease {
+    url: string;
+    sha256: string;
+    bytes: number;
+    image: string;
+}
+export interface LocalRuntimeStatus {
+    ok: boolean;
+    installed: boolean;
+    message: string;
+    assets?: LocalFirecrackerAssets;
+}
+interface RuntimeOptions extends RuntimeHostOptions {
+    media?: boolean;
+    progress?: (message: string) => void;
+    /** Explicit source-build/test override; never provided by a participant. */
+    release?: LocalRuntimeRelease;
+}
+/** Read-only host and cache inspection. Never pulls an image or starts a container. */
+export declare function localRuntimeStatus(options?: RuntimeOptions): Promise<LocalRuntimeStatus>;
+/** Docker owns the installed image/cache. The archive is verified before docker load. */
+export declare function prepareLocalRuntime(options?: RuntimeOptions): Promise<LocalFirecrackerAssets>;
+export {};

package/dist/substrates/local/runtime.js

@@ -0,0 +1,190 @@
+import { createHash } from "node:crypto";
+import { createWriteStream } from "node:fs";
+import { access, mkdtemp, rm } from "node:fs/promises";
+import { tmpdir } from "node:os";
+import path from "node:path";
+import { Readable, Transform } from "node:stream";
+import { pipeline } from "node:stream/promises";
+import { LOCAL_MEDIA_RUNTIME_RELEASES, LOCAL_RUNTIME_RELEASES } from "./runtime-release.js";
+import { limaStatus, loadRuntimeArchive, prepareLima, runtimeArchitecture, runtimeDocker, runtimeExec, usesLima, } from "./runtime-host.js";
+const docker = async (args, options) => (await runtimeDocker(args, options)).stdout.trim();
+const runtimeRelease = (options) => options.release ??
+    (options.media ? LOCAL_MEDIA_RUNTIME_RELEASES : LOCAL_RUNTIME_RELEASES)[runtimeArchitecture(options) ?? "amd64"];
+/** Read-only host and cache inspection. Never pulls an image or starts a container. */
+export async function localRuntimeStatus(options = {}) {
+    const architecture = runtimeArchitecture(options), lima = usesLima(options);
+    if (!architecture)
+        return {
+            ok: false,
+            installed: false,
+            message: "Local browsers need Linux x64 or an M3-or-newer Mac with Lima.",
+        };
+    if (lima) {
+        try {
+            const status = await limaStatus(options);
+            if (!status.ready)
+                return { ok: true, installed: false, message: status.message };
+        }
+        catch (error) {
+            return { ok: false, installed: false, message: error.message };
+        }
+    }
+    const env = options.env ?? process.env;
+    if (!lima && env.DOCKER_HOST && !env.DOCKER_HOST.startsWith("unix://")) {
+        return {
+            ok: false,
+            installed: false,
+            message: "Local browsers need Docker on this machine; a remote DOCKER_HOST cannot reach the local app and control socket.",
+        };
+    }
+    try {
+        if (lima)
+            await runtimeExec("sh", ["-c", "test -c /dev/kvm && test -c /dev/net/tun"], options);
+        else {
+            await access("/dev/kvm");
+            await access("/dev/net/tun");
+        }
+    }
+    catch {
+        return {
+            ok: false,
+            installed: false,
+            message: "Local browsers need Linux KVM (/dev/kvm) and TUN (/dev/net/tun). Enable virtualization on this host.",
+        };
+    }
+    try {
+        if (!lima && (env.DOCKER_CONTEXT || !env.DOCKER_HOST)) {
+            const endpoint = JSON.parse(await docker(["context", "inspect", "--format", "{{json .Endpoints.docker.Host}}"], options));
+            if (typeof endpoint !== "string" || !endpoint.startsWith("unix://")) {
+                return {
+                    ok: false,
+                    installed: false,
+                    message: "Select a local Docker context. Remote Docker cannot reach the local app and control socket.",
+                };
+            }
+        }
+        const info = JSON.parse(await docker(["info", "--format", "{{json .}}"], options));
+        if (info.OSType !== "linux" ||
+            !(architecture === "amd64" ? ["x86_64", "amd64"] : ["aarch64", "arm64"]).includes(info.Architecture) ||
+            info.SecurityOptions?.some((value) => value.includes("rootless"))) {
+            return {
+                ok: false,
+                installed: false,
+                message: "Local browsers need a local, rootful Linux Docker engine of the matching architecture with KVM access.",
+            };
+        }
+    }
+    catch {
+        return {
+            ok: false,
+            installed: false,
+            message: lima
+                ? "Docker is unavailable inside the humanish Lima host. Check limactl shell humanish-runtime -- sudo systemctl status docker; Docker Desktop is not used."
+                : "Docker is unavailable. Install/start Docker Engine and give your account access, then run humanish runtime setup.",
+        };
+    }
+    const release = runtimeRelease(options);
+    const imageVariable = options.media
+        ? "HUMANISH_LOCAL_MEDIA_RUNTIME_IMAGE"
+        : "HUMANISH_LOCAL_RUNTIME_IMAGE";
+    const reference = env[imageVariable]?.trim() || release?.image;
+    if (!reference)
+        return {
+            ok: false,
+            installed: false,
+            message: `This build does not include a published local ${options.media ? "media " : ""}runtime. Source builds can set ${imageVariable}.`,
+        };
+    let images;
+    try {
+        images = JSON.parse(await docker(["image", "inspect", reference], options));
+    }
+    catch {
+        return env[imageVariable]?.trim()
+            ? {
+                ok: false,
+                installed: false,
+                message: `${imageVariable} must name an already-built local image. Build or load it before running.`,
+            }
+            : {
+                ok: true,
+                installed: false,
+                message: "Local runtime will download before the first live run. Run humanish runtime setup to prepare it now.",
+            };
+    }
+    const image = images[0];
+    const labels = image?.Config?.Labels ?? {};
+    const revision = labels["to.humanish.runtime.revision"];
+    if (image?.Os !== "linux" ||
+        image.Architecture !== architecture ||
+        labels["to.humanish.runtime.api"] !== "1" ||
+        typeof revision !== "string" ||
+        !/^guest-api1-[a-f0-9]{64}$/.test(revision) ||
+        (options.media === true && labels["to.humanish.runtime.media"] !== "1")) {
+        return {
+            ok: false,
+            installed: false,
+            message: "The cached image is not a compatible humanish local browser runtime.",
+        };
+    }
+    return {
+        ok: true,
+        installed: true,
+        message: `Local ${options.media ? "media" : "browser"} runtime is installed. No E2B key is needed.`,
+        assets: {
+            image: image.Id,
+            runtimeRevision: revision,
+            ...(labels["to.humanish.runtime.media"] === "1" ? { media: true } : {}),
+        },
+    };
+}
+/** Docker owns the installed image/cache. The archive is verified before docker load. */
+export async function prepareLocalRuntime(options = {}) {
+    if (!runtimeArchitecture(options))
+        throw new Error((await localRuntimeStatus(options)).message);
+    if (usesLima(options))
+        await prepareLima(options, options.progress);
+    const before = await localRuntimeStatus(options);
+    if (!before.ok)
+        throw new Error(before.message);
+    if (before.assets)
+        return before.assets;
+    const release = runtimeRelease(options);
+    if (!release)
+        throw new Error(before.message);
+    options.progress?.(`Downloading local browser runtime (${Math.ceil(release.bytes / 1024 / 1024)} MiB)…`);
+    const work = await mkdtemp(path.join(tmpdir(), "humanish-runtime-download-"));
+    const archive = path.join(work, "runtime.tar.gz");
+    const signal = AbortSignal.any([
+        AbortSignal.timeout(30 * 60_000),
+        ...(options.signal ? [options.signal] : []),
+    ]);
+    try {
+        const response = await fetch(release.url, { signal });
+        if (!response.ok || !response.body)
+            throw new Error(`Runtime download failed (HTTP ${response.status}). Run humanish runtime setup to retry.`);
+        let bytes = 0;
+        const hash = createHash("sha256");
+        await pipeline(Readable.fromWeb(response.body), new Transform({
+            transform(chunk, _encoding, done) {
+                bytes += chunk.length;
+                if (bytes > release.bytes) {
+                    done(new Error("Runtime archive exceeds its published size."));
+                    return;
+                }
+                hash.update(chunk);
+                done(null, chunk);
+            },
+        }), createWriteStream(archive, { flags: "wx", mode: 0o600 }), { signal });
+        if (bytes !== release.bytes || hash.digest("hex") !== release.sha256)
+            throw new Error("Runtime archive integrity check failed; it was not installed.");
+        options.progress?.("Installing the local browser image…");
+        await loadRuntimeArchive(archive, { ...options, signal });
+        const after = await localRuntimeStatus(options);
+        if (!after.assets)
+            throw new Error("Downloaded runtime did not provide the expected image. Run humanish runtime setup to retry.");
+        return after.assets;
+    }
+    finally {
+        await rm(work, { recursive: true, force: true });
+    }
+}

package/dist/substrates/shell.d.ts

@@ -0,0 +1,44 @@
+export interface ShellResult {
+    exitCode: number;
+    stdout: string;
+    stderr: string;
+}
+export interface ShellCallOptions {
+    /** How long to wait for the machine to answer the call. */
+    requestTimeoutMs?: number;
+    /** How long the command itself may run. */
+    timeoutMs?: number;
+    /** Environment for this command only, added to the machine's own. */
+    env?: Readonly<Record<string, string>>;
+}
+interface ShellWriteOptions {
+    requestTimeoutMs?: number;
+    /**
+     * Retry a transient transport failure once. The provider decides what is transient. Writes
+     * replace the whole file, so a repeat is safe.
+     */
+    retryOnce?: {
+        onRetry?: (reason: string) => void;
+        sleep?: (ms: number) => Promise<void>;
+    };
+}
+export interface Shell {
+    /** Run a command to completion. A non-zero exit resolves as a result; only transport rejects. */
+    run(command: string, options?: ShellCallOptions): Promise<ShellResult>;
+    /**
+     * Launch a command in its own session and resolve once it is launched, without waiting for it
+     * to exit. The result is the launcher's. The machine's lifetime reclaims the process.
+     */
+    start(command: string, options?: ShellCallOptions): Promise<ShellResult>;
+    /** Create or replace a file. */
+    writeFile(path: string, data: string | ArrayBuffer, options?: ShellWriteOptions): Promise<void>;
+}
+/** Run a command whose non-zero exit the caller cannot use, and reject on one. */
+export declare function runOrThrow(shell: Shell, command: string, options?: ShellCallOptions): Promise<ShellResult>;
+/** Reject a non-zero result with its exit code and a short tail of its output. */
+export declare function throwOnExit(result: ShellResult): ShellResult;
+/** Single-quote a value for a Shell command line. */
+export declare function shellQuote(value: string): string;
+/** Sanitized, whitespace-collapsed, length-capped tail of command output. */
+export declare function tailOf(value: string | undefined): string;
+export {};

package/dist/substrates/shell.js

@@ -0,0 +1,22 @@
+// The command channel into a machine. Subject provisioning and in-sandbox comms use only this, so
+// a machine provider has to supply a Shell for them to run there. The E2B implementation is
+// src/substrates/e2b/shell.ts.
+/** Run a command whose non-zero exit the caller cannot use, and reject on one. */
+export async function runOrThrow(shell, command, options) {
+    return throwOnExit(await shell.run(command, options));
+}
+/** Reject a non-zero result with its exit code and a short tail of its output. */
+export function throwOnExit(result) {
+    if (result.exitCode === 0)
+        return result;
+    const tail = tailOf(result.stderr || result.stdout);
+    throw new Error(`command exited ${result.exitCode}${tail ? `: ${tail}` : ""}`);
+}
+/** Single-quote a value for a Shell command line. */
+export function shellQuote(value) {
+    return `'${value.replace(/'/g, "'\\''")}'`;
+}
+/** Sanitized, whitespace-collapsed, length-capped tail of command output. */
+export function tailOf(value) {
+    return (value ?? "").trim().replace(/\s+/g, " ").slice(-240);
+}

package/dist/tui/actions.d.ts

@@ -0,0 +1,39 @@
+import { openTarget } from "../observer/render.js";
+export declare const TUI_ACTION_SCHEMA = "humanish.tui-action.v1";
+export interface TuiActionResult {
+    schema: typeof TUI_ACTION_SCHEMA;
+    ok: boolean;
+    /** What to tell the operator. Always set: an action that appears to do nothing is a bug. */
+    message: string;
+}
+/** A TUI owns one evidence server, shared by its open browser tabs and closed when it exits. */
+export interface TuiObserverSession {
+    open(cwd: string, observerPath: string): Promise<TuiActionResult>;
+    close(): Promise<void>;
+}
+/**
+ * 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 declare function createTuiObserverSession(cwdInput: string, options?: {
+    openTarget?: typeof openTarget;
+}): TuiObserverSession;
+/**
+ * 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 declare function stopRun(cwd: string, runId: string, intent?: "run" | "analysis"): Promise<TuiActionResult>;