humanish 0.140.0 → 0.142.0

package/dist/remote/reattach.js

@@ -0,0 +1,81 @@
+// Coming back to a remote run whose launcher let it go (a closed terminal): find its runner from
+// the run directory here, serve its live Observer again and follow it to the end, as the launcher
+// would have.
+import { readContainedRegularFile } from "../run/contained-output.js";
+import { bindExistingRunArtifactPaths } from "../run/paths.js";
+import { isSandboxProviderId, parseSandboxReceipts, SANDBOX_RECEIPTS_ARTIFACT, } from "../run/sandbox-receipts.js";
+import { loadE2BBaseModule } from "../substrates/e2b/base-module.js";
+import { e2bConnection } from "../substrates/e2b/connection.js";
+import { isSandboxNotFoundError } from "../substrates/e2b/sdk.js";
+import { loadModalShellModule } from "../substrates/modal/sandbox.js";
+import { followRemoteRun, watchSignals } from "./launch.js";
+import { serveObserverProxy } from "./observer-proxy.js";
+import { RUNNER_OBSERVER_PORT, runnerOf } from "./runner.js";
+/**
+ * The remote run `runId` names, when its directory here has a remote.json and no run.json yet;
+ * undefined for any other run, which the Observer serves from its files as before.
+ */
+export async function remoteRunHere(cwd, runId) {
+    let paths;
+    try {
+        paths = await bindExistingRunArtifactPaths(cwd, runId);
+    }
+    catch {
+        return undefined;
+    }
+    if ((await readText(paths, "run.json")) !== undefined)
+        return undefined;
+    const record = await readText(paths, "remote.json");
+    if (record === undefined)
+        return undefined;
+    const provider = JSON.parse(record).provider;
+    if (typeof provider !== "string" || !isSandboxProviderId(provider))
+        return undefined;
+    const journal = (await readText(paths, SANDBOX_RECEIPTS_ARTIFACT)) ?? "";
+    // Until the run is copied back, this directory's journal holds one receipt: the runner's, the
+    // only sandbox this machine creates for a remote run.
+    const [runner, ...others] = parseSandboxReceipts(journal);
+    if (runner === undefined || others.length > 0)
+        return undefined;
+    return { paths, runId, provider, runnerId: runner.sandboxId };
+}
+async function readText(root, file) {
+    const read = await readContainedRegularFile(root, file, 16 * 1024 * 1024);
+    return read.status === "read" ? Buffer.from(read.bytes).toString("utf8") : undefined;
+}
+/** Reconnect to `run`'s runner, serve its Observer on 127.0.0.1:`port` and follow it to the end. */
+export async function reattachRemoteRun(context, run, port) {
+    const module = run.provider === "modal" ? await loadModalShellModule(context.env) : await loadE2BBaseModule();
+    let sandbox;
+    try {
+        // A Modal module takes its connection from context.env and ignores this one.
+        sandbox = await module.Sandbox.connect(run.runnerId, e2bConnection(context.env));
+    }
+    catch (error) {
+        if (!isSandboxNotFoundError(error))
+            throw error;
+        return {
+            runId: run.runId,
+            exitCode: 2,
+            error: `its runner sandbox is gone, so the run was not copied back. Stop anything it left with humanish reclaim --run ${run.runId}`,
+        };
+    }
+    const runner = runnerOf(sandbox);
+    const signals = watchSignals();
+    const proxy = await serveObserverProxy(await runner.sandbox.portAccess(RUNNER_OBSERVER_PORT), port);
+    try {
+        context.say(`Reconnected to run ${run.runId} on its runner.`);
+        return await followRemoteRun({
+            launch: context,
+            runner,
+            paths: run.paths,
+            runId: run.runId,
+            signals,
+            proxyUrl: proxy.url,
+        });
+    }
+    finally {
+        signals.dispose();
+        await proxy.close();
+    }
+}

package/dist/remote/runner.d.ts

@@ -0,0 +1,68 @@
+import type { E2BDesktopSandbox } from "../substrates/e2b/sdk.js";
+import { type Shell } from "../substrates/shell.js";
+/** The port the runner's Observer listens on. */
+export declare const RUNNER_OBSERVER_PORT = 7000;
+/** A runner sandbox and the shell into it. */
+export interface Runner {
+    readonly sandbox: E2BDesktopSandbox;
+    readonly shell: Shell;
+}
+export declare function runnerOf(sandbox: E2BDesktopSandbox): Runner;
+/**
+ * Install Node and the humanish package `tarball` (this machine's own humanish, packed), with the
+ * provider SDKs its participants need at `peers` (name@version). Returns the installed version.
+ */
+export declare function installHumanish(runner: Runner, tarball: Uint8Array, peers: readonly string[]): Promise<string>;
+/**
+ * Upload each project-relative file in `files`, and every file under each directory in
+ * `directories` that exists here, to the same place in the runner's project.
+ */
+export declare function uploadProject(runner: Runner, cwd: string, files: readonly string[], directories: readonly string[]): Promise<number>;
+/** What the runner's run is started with. */
+export interface RemoteRunStart {
+    /** The study file, relative to the project. */
+    study: string;
+    runId: string;
+    ownerKey: string;
+    /** Only these names reach the run, each with its value from this machine. */
+    env: Readonly<Record<string, string>>;
+}
+/**
+ * Start the study's run in the runner as `humanish watch --serve`, so the run process itself serves
+ * the Observer with its live desktop streams, and writes its result to a file the launcher reads.
+ */
+export declare function startRemoteRun(runner: Runner, start: RemoteRunStart): Promise<void>;
+/** How the runner's run is going, read from its own files. */
+export interface RemoteRunState {
+    /** status.json's `state`, once the run has written one. */
+    state?: string;
+    /** The result the run wrote when it ended, with the exit code the command would return. */
+    result?: {
+        exitCode: number;
+        result: unknown;
+    };
+    /** Whether the run's process is still alive in the runner. */
+    alive: boolean;
+    /** The last lines the run wrote to stderr. */
+    errTail: string;
+}
+export declare function readRemoteRun(runner: Runner, runId: string): Promise<RemoteRunState>;
+/** One file of the runner's run directory: its path in the directory and its sha256. */
+export interface RemoteFile {
+    path: string;
+    sha256: string;
+}
+/**
+ * The regular files of the runner's run directory and their digests. Refuses a directory that holds
+ * a link, which a run never writes.
+ */
+export declare function listRemoteRun(runner: Runner, runId: string): Promise<RemoteFile[]>;
+/** sha256sum lines, `<hex>  ./<path>`, as RemoteFiles with paths relative to the directory. */
+export declare function parseDigests(output: string): RemoteFile[];
+/** The bytes of one file of the runner's run directory, checked against its listed digest. */
+export declare function readRemoteFile(runner: Runner, runId: string, file: RemoteFile): Promise<Uint8Array>;
+/**
+ * Ask the runner's run to stop as a signal would, so it reclaims its participants and ends. The
+ * `[h]` keeps the pattern from matching the shell that runs it.
+ */
+export declare function stopRemoteRun(runner: Runner): Promise<void>;

package/dist/remote/runner.js

@@ -0,0 +1,216 @@
+// What the launcher does inside a runner sandbox, over the sandbox port's commands and files: install
+// Node and this humanish, upload the study's files, start its run, read how it is going, and copy
+// the finished run back.
+import { createHash } from "node:crypto";
+import { lstat, readFile, readdir, realpath } from "node:fs/promises";
+import path from "node:path";
+import { e2bShell } from "../substrates/e2b/shell.js";
+import { shellQuote } from "../substrates/shell.js";
+import { tailOf } from "../substrates/shell.js";
+/** The project directory in the runner, under the sandbox user's home on both providers. */
+const RUNNER_PROJECT = "project";
+/** Where the runner keeps the launcher's own files: the result file and the run's output. */
+const RUNNER_STATE = ".humanish-remote";
+/** The port the runner's Observer listens on. */
+export const RUNNER_OBSERVER_PORT = 7000;
+/**
+ * The Node release the runner runs humanish on, with the sha256 nodejs.org publishes for each
+ * build (SHASUMS256.txt). The runner checks the download against it before extracting.
+ */
+const NODE = {
+    version: "22.23.4",
+    sha256: {
+        x64: "b8492284c76a54baf58d61668dd0e41ee0fc98adabf9503d30f05d08f55b4406",
+        arm64: "f7a1e486dbc8b286847815b477d4fb5e9fb963ed4489c3e1588853d685f589f9",
+    },
+};
+export function runnerOf(sandbox) {
+    return { sandbox, shell: e2bShell(sandbox) };
+}
+/** A command failed in the runner; the message carries its exit code and output tail. */
+class RunnerCommandError extends Error {
+    constructor(step, result) {
+        super(`${step} failed in the runner sandbox (exit ${result.exitCode}): ${tailOf(result.stderr || result.stdout)}`);
+        this.name = "RunnerCommandError";
+    }
+}
+async function runOrFail(runner, step, command, timeoutMs) {
+    const result = await runner.shell.run(command, { timeoutMs });
+    if (result.exitCode !== 0)
+        throw new RunnerCommandError(step, result);
+    return result;
+}
+/**
+ * Install Node and the humanish package `tarball` (this machine's own humanish, packed), with the
+ * provider SDKs its participants need at `peers` (name@version). Returns the installed version.
+ */
+export async function installHumanish(runner, tarball, peers) {
+    await runner.shell.writeFile(`${RUNNER_STATE}/humanish.tgz`, toArrayBuffer(tarball));
+    const { version, sha256 } = NODE;
+    const script = [
+        "set -eu",
+        `cd "$HOME/${RUNNER_STATE}"`,
+        'case "$(uname -m)" in x86_64) arch=x64;; aarch64|arm64) arch=arm64;; *) echo "unsupported CPU $(uname -m)" >&2; exit 1;; esac',
+        `if [ "$arch" = x64 ]; then sum=${sha256.x64}; else sum=${sha256.arm64}; fi`,
+        `curl -fsSL -o node.tgz "https://nodejs.org/dist/v${version}/node-v${version}-linux-$arch.tar.gz"`,
+        'echo "$sum  node.tgz" | sha256sum -c - >/dev/null',
+        "mkdir -p node && tar -xzf node.tgz --strip-components=1 -C node && rm node.tgz",
+        `export PATH="$HOME/${RUNNER_STATE}/node/bin:$PATH" npm_config_prefix="$HOME/${RUNNER_STATE}/node"`,
+        `npm install -g --no-fund --no-audit --loglevel=error ./humanish.tgz ${peers.map(shellQuote).join(" ")}`,
+        "humanish --version",
+    ].join("\n");
+    const result = await runOrFail(runner, "Installing humanish", `bash -c ${shellQuote(script)}`, 600_000);
+    return result.stdout.trim().split("\n").at(-1) ?? "";
+}
+/**
+ * Upload each project-relative file in `files`, and every file under each directory in
+ * `directories` that exists here, to the same place in the runner's project.
+ */
+export async function uploadProject(runner, cwd, files, directories) {
+    const all = new Set(files);
+    for (const directory of directories)
+        for (const file of await filesUnder(cwd, directory))
+            all.add(file);
+    const root = await realpath(cwd);
+    for (const file of all) {
+        // A link could hand the runner a file from anywhere on this machine, such as a key file, so
+        // only a regular file whose real path is where the study names it is uploaded.
+        const real = await realpath(path.join(cwd, file)).catch(() => undefined);
+        if (real !== path.join(root, file) || !(await lstat(real)).isFile())
+            throw new Error(`${file} is a link or not a regular file, so it is not uploaded to the runner.`);
+        const bytes = await readFile(real);
+        await runner.shell.writeFile(`${RUNNER_PROJECT}/${file}`, toArrayBuffer(bytes));
+    }
+    return all.size;
+}
+async function filesUnder(cwd, directory) {
+    let entries;
+    try {
+        entries = await readdir(path.join(cwd, directory), { recursive: true, withFileTypes: true });
+    }
+    catch {
+        return [];
+    }
+    return entries
+        .filter((entry) => entry.isFile())
+        .map((entry) => path.relative(cwd, path.join(entry.parentPath, entry.name)).split(path.sep).join("/"));
+}
+/**
+ * Start the study's run in the runner as `humanish watch --serve`, so the run process itself serves
+ * the Observer with its live desktop streams, and writes its result to a file the launcher reads.
+ */
+export async function startRemoteRun(runner, start) {
+    const args = [
+        "humanish",
+        "watch",
+        start.study,
+        "--serve",
+        "--no-open",
+        "--port",
+        String(RUNNER_OBSERVER_PORT),
+        "--all-interfaces",
+        "--result-file",
+        `$HOME/${RUNNER_STATE}/result.json`,
+        "--run-id",
+        start.runId,
+        "--owner-key",
+        start.ownerKey,
+    ];
+    const line = [
+        `cd "$HOME/${RUNNER_PROJECT}"`,
+        `export PATH="$HOME/${RUNNER_STATE}/node/bin:$PATH"`,
+        `exec ${args.map((arg) => (arg.startsWith("$HOME") ? `"${arg}"` : shellQuote(arg))).join(" ")} > "$HOME/${RUNNER_STATE}/watch.out" 2> "$HOME/${RUNNER_STATE}/watch.err"`,
+    ].join("; ");
+    const env = { ...start.env, DO_NOT_TRACK: "1", HUMANISH_TELEMETRY_DISABLED: "1" };
+    const result = await runner.shell.start(`bash -c ${shellQuote(line)}`, {
+        env,
+        timeoutMs: 60_000,
+    });
+    if (result.exitCode !== 0)
+        throw new RunnerCommandError("Starting the run", result);
+}
+export async function readRemoteRun(runner, runId) {
+    const read = async (file) => {
+        const result = await runner.shell.run(`cat -- ${shellQuote(file)} 2>/dev/null`, {
+            timeoutMs: 30_000,
+        });
+        return result.exitCode === 0 ? result.stdout : undefined;
+    };
+    const status = parseJson(await read(`${RUNNER_PROJECT}/.humanish/runs/${runId}/status.json`));
+    const result = parseJson(await read(`${RUNNER_STATE}/result.json`));
+    const err = await runner.shell.run(`tail -c 2000 ${RUNNER_STATE}/watch.err 2>/dev/null`, {
+        timeoutMs: 30_000,
+    });
+    const alive = await runner.shell.run("pgrep -f '[h]umanish watch' >/dev/null", {
+        timeoutMs: 30_000,
+    });
+    return {
+        ...(typeof status?.state === "string" ? { state: status.state } : {}),
+        ...(typeof result?.exitCode === "number"
+            ? { result: { exitCode: result.exitCode, result: result.result } }
+            : {}),
+        alive: alive.exitCode === 0,
+        errTail: tailOf(err.stdout),
+    };
+}
+function parseJson(text) {
+    if (text === undefined)
+        return undefined;
+    try {
+        const value = JSON.parse(text);
+        return value !== null && typeof value === "object"
+            ? value
+            : undefined;
+    }
+    catch {
+        return undefined;
+    }
+}
+/**
+ * The regular files of the runner's run directory and their digests. Refuses a directory that holds
+ * a link, which a run never writes.
+ */
+export async function listRemoteRun(runner, runId) {
+    const dir = `${RUNNER_PROJECT}/.humanish/runs/${runId}`;
+    const links = await runOrFail(runner, "Listing the run", `cd ${shellQuote(dir)} && find . ! -type f ! -type d -print -quit`, 60_000);
+    if (links.stdout.trim() !== "")
+        throw new Error(`The runner's run directory holds something other than files and folders (${tailOf(links.stdout)}), so it is not copied.`);
+    const listed = await runOrFail(runner, "Listing the run", `cd ${shellQuote(dir)} && find . -type f -print0 | xargs -0 -r sha256sum`, 300_000);
+    return parseDigests(listed.stdout);
+}
+/** sha256sum lines, `<hex>  ./<path>`, as RemoteFiles with paths relative to the directory. */
+export function parseDigests(output) {
+    const files = [];
+    for (const line of output.split("\n")) {
+        const match = /^([0-9a-f]{64}) [ *]\.\/(.+)$/.exec(line);
+        if (match === null)
+            continue;
+        files.push({ sha256: match[1], path: match[2] });
+    }
+    return files;
+}
+/** The bytes of one file of the runner's run directory, checked against its listed digest. */
+export async function readRemoteFile(runner, runId, file) {
+    const read = runner.sandbox.files.read;
+    if (read === undefined)
+        throw new Error("This sandbox cannot read files back.");
+    const stream = await read.call(runner.sandbox.files, `${RUNNER_PROJECT}/.humanish/runs/${runId}/${file.path}`, { format: "stream", requestTimeoutMs: 300_000 });
+    const parts = [];
+    for await (const chunk of stream)
+        parts.push(chunk);
+    const bytes = Buffer.concat(parts);
+    const digest = createHash("sha256").update(bytes).digest("hex");
+    if (digest !== file.sha256)
+        throw new Error(`${file.path} changed or arrived damaged while it was copied from the runner.`);
+    return bytes;
+}
+/**
+ * Ask the runner's run to stop as a signal would, so it reclaims its participants and ends. The
+ * `[h]` keeps the pattern from matching the shell that runs it.
+ */
+export async function stopRemoteRun(runner) {
+    await runner.shell.run("pkill -TERM -f '[h]umanish watch' || true", { timeoutMs: 30_000 });
+}
+function toArrayBuffer(bytes) {
+    return bytes.buffer.slice(bytes.byteOffset, bytes.byteOffset + bytes.byteLength);
+}

package/dist/routes/computer-use/e2b-desktop/desktop.js

@@ -1,4 +1,6 @@
+import { externalHandoffReader } from "../../../substrates/e2b/desktop-handoff.js";
 import { createE2BDesktopExecutor } from "../../../substrates/e2b/desktop-executor.js";
+import { e2bShell } from "../../../substrates/e2b/shell.js";
 import { participantInbox, planParticipantComms } from "./comms.js";
 import { participantBrowserStateObserver } from "./fidelity.js";
 import { networkHooks, planParticipantNetwork } from "./network.js";
@@ -37,7 +39,7 @@ export function createE2BParticipantDesktop(spec, deps, warnings) {
     let finalization;
     async function prepare() {
         if (preparationStarted || finalization)
-            throw new Error("Participant desktop preparation can only start once, before finalization.");
+            throw new Error("Participant desktop preparation can only start once, before the desktop is released.");
         preparationStarted = true;
         const desktop = await acquireParticipantDesktop(ctx, state);
         // The device claim is verified in the sandbox, and fails closed.
@@ -52,7 +54,7 @@ export function createE2BParticipantDesktop(spec, deps, warnings) {
     async function openSession() {
         const { desktop, allocation } = state;
         if (!prepared || !desktop || !allocation || opened || finalization)
-            throw new Error("The participant desktop must be prepared and may only be opened once, before finalization.");
+            throw new Error("The participant desktop must be prepared and may only be opened once, before the desktop is released.");
         opened = true;
         await startParticipantStream(ctx, state, desktop);
         const inbox = participantInbox({
@@ -64,21 +66,29 @@ export function createE2BParticipantDesktop(spec, deps, warnings) {
         });
         // Capture that started pairs each checkpoint with the time of the read before it.
         const network = networkHooks(state.network);
-        const executor = createE2BDesktopExecutor(desktop, state.launchedBrowserFamily === "chromium"
-            ? {
-                observeBrowserState: participantBrowserStateObserver({
-                    desktop,
-                    spec,
-                    deps,
-                    targetUrl,
-                    launchIdentity: state.browserLaunchIdentity,
-                    targetId: state.browserTargetId,
-                    fidelity: state.fidelity,
-                    warnings,
-                    ...(network === undefined ? {} : { onClock: network.onClock }),
-                }),
-            }
-            : {});
+        // A web target's browser launch installs the stand-ins that write handed-off links down
+        // (desktop-handoff.ts). Without them the log is absent and every read is empty.
+        const readExternalHandoffs = state.browserLaunched
+            ? externalHandoffReader(e2bShell(desktop), { requestTimeoutMs: deps.requestTimeoutMs })
+            : undefined;
+        const executor = createE2BDesktopExecutor(desktop, {
+            ...(readExternalHandoffs === undefined ? {} : { readExternalHandoffs }),
+            ...(state.launchedBrowserFamily === "chromium"
+                ? {
+                    observeBrowserState: participantBrowserStateObserver({
+                        desktop,
+                        spec,
+                        deps,
+                        targetUrl,
+                        launchIdentity: state.browserLaunchIdentity,
+                        targetId: state.browserTargetId,
+                        fidelity: state.fidelity,
+                        warnings,
+                        ...(network === undefined ? {} : { onClock: network.onClock }),
+                    }),
+                }
+                : {}),
+        });
         return {
             executor: allocation.open(state.speech?.wrap(executor) ?? executor).executor,
             ...(inbox === undefined ? {} : { inbox }),

package/dist/routes/computer-use/e2b-desktop/start.js

@@ -203,7 +203,7 @@ export async function startParticipantStream(ctx, state, desktop) {
         // A browser participant streams its browser window when one was found. A CLI participant has
         // no window id and streams the whole desktop: a person studying a terminal app opens other windows, and
         // a stream bound to the first one would quietly stop being evidence.
-        await startDesktopStream(desktop, state.browserWindowId);
+        await startDesktopStream(desktop, state.browserWindowId, deps.requestTimeoutMs);
         const candidateStreamUrl = desktop.stream.getUrl({
             authKey: desktop.stream.getAuthKey(),
             autoConnect: true,

package/dist/routes/computer-use/e2b-desktop/teardown.js

@@ -106,7 +106,7 @@ export async function finishE2BDesktop(ctx, state, failed) {
                 await deps.receiving.finishParticipant(spec.planned.id);
             }
             catch {
-                warnings.push("Real email finalization is incomplete. Inspect communication cleanup with humanish comms recover.");
+                warnings.push("Real email cleanup is incomplete. Inspect communication cleanup with humanish comms recover.");
             }
         }
         if (ctx.comms && state.commsCatch?.deployed.ready) {

package/dist/routes/computer-use/in-process-desktop.js

@@ -12,12 +12,12 @@ export function createInProcessDesktop(deps) {
     return {
         async prepare() {
             if (preparationStarted || finalization)
-                throw new Error("Participant desktop preparation can only start once, before finalization.");
+                throw new Error("Participant desktop preparation can only start once, before the desktop is released.");
             preparationStarted = true;
         },
         async openSession() {
             if (!preparationStarted || opened || finalization)
-                throw new Error("The participant desktop must be prepared and may only be opened once, before finalization.");
+                throw new Error("The participant desktop must be prepared and may only be opened once, before the desktop is released.");
             opened = true;
             if (deps.inProcessExecutor === undefined)
                 throw new Error("The in-process route needs RunStudyOptions.inProcess.");

package/dist/routes/computer-use/live-phase.js

@@ -110,7 +110,7 @@ export async function runStudyParticipants(setup, participants) {
             await receiving?.finish();
         }
         catch {
-            receivingWarnings.push("Email finalization could not complete. Inspect humanish comms recover; provider cleanup remains unresolved.");
+            receivingWarnings.push("Email cleanup could not complete. Inspect humanish comms recover; provider cleanup remains unresolved.");
         }
         // Stop the flush timer on every exit, including a throw from the participants.
         await liveTrace.stop?.();

package/dist/routes/computer-use/setup.js

@@ -233,8 +233,8 @@ export async function startCuaRun(plan, input, admitted, scope) {
     const { cwd, descriptor, participantRuns, participantPlan, publicRepo } = admitted;
     const { appUrl } = admitted;
     // The run's status record exists from here on, so anything watching the runs directory can
-    // tell which study this is and that it is alive. The fail-closed returns below leave it finished
-    // with no outcome when the scope closes; a crash leaves it stale, which reads as interrupted.
+    // tell which study this is and that it is alive. The fail-closed returns below leave it
+    // interrupted with no outcome when the scope closes; a killed process leaves it stale.
     const started = await scope.startRun(plan, input, {
         cwd,
         prefix: "cua",

package/dist/routes/computer-use/types.d.ts

@@ -59,6 +59,8 @@ export interface ComputerUseRunInput {
     cwd: string;
     open?: boolean;
     runId?: string;
+    /** The run key its sandboxes carry; see InternalRunStudyOptions.ownerKey. */
+    ownerKey?: string;
     /** CLI `--count` override for the homogeneous fan-out participant count (ignored when a `participants`
      *  list is declared; a roster's length is authoritative). */
     countOverride?: number;

package/dist/routes/scripted/types.d.ts

@@ -15,6 +15,8 @@ export interface ScriptedRunInput {
     cwd: string;
     open?: boolean;
     runId?: string;
+    /** The run key its sandboxes carry; see InternalRunStudyOptions.ownerKey. */
+    ownerKey?: string;
     /** Keys and subject env for the run. Defaults to process.env. Values are scrubbed; names persist. */
     env?: Readonly<Record<string, string | undefined>>;
     /** Runs after a clone subject's sandbox exists and before provisioning. */

package/dist/routes/shared-world/route.js

@@ -226,7 +226,7 @@ async function runPlane(ctx, live, results, plane) {
             await ctx.receiving?.finish();
         }
         catch {
-            ctx.warnings.push("Email finalization could not complete. Inspect humanish comms recover; provider cleanup remains unresolved.");
+            ctx.warnings.push("Email cleanup could not complete. Inspect humanish comms recover; provider cleanup remains unresolved.");
         }
         // Stop the participants' flush timer on every exit, before the final write.
         await live.flush?.stop();

package/dist/routes/shared-world/types.d.ts

@@ -31,6 +31,8 @@ export interface SharedWorldRunInput {
     cwd: string;
     open?: boolean;
     runId?: string;
+    /** The run key its sandboxes carry; see InternalRunStudyOptions.ownerKey. */
+    ownerKey?: string;
     onObserverReady?: (observer: ObserverResult & {
         ok: true;
     }) => Promise<void> | void;

package/dist/routes/terminal/types.d.ts

@@ -106,6 +106,8 @@ export interface TerminalRunInput {
     cwd: string;
     open?: boolean;
     runId?: string;
+    /** The run key its sandboxes carry; see InternalRunStudyOptions.ownerKey. */
+    ownerKey?: string;
     /**
      * The operator environment the route reads the runtime key from (and from which it asserts no
      * banned credential is requested). Defaults to process.env. The runtime key goes only

package/dist/run/costs.d.ts

@@ -1,5 +1,6 @@
 import { type PreparedRunArtifactPaths } from "./paths.js";
 import type { RunIndexEntry } from "./run-index.js";
+import type { AnalysisProviderName } from "../analysis/types.js";
 /** Additive accounting for retained attempts. Null means no estimate, never an invented zero. */
 export interface CostTotals {
     estimatedTotalUsd: number | null;
@@ -39,7 +40,7 @@ export interface AnalysisAccounting {
     /** The known estimates of the dispatched attempts; 0 when every attempt sent nothing. */
     estimatedUsd: number | null;
     /** Who billed the dispatched attempts. */
-    providers: Array<"openai" | "codex">;
+    providers: AnalysisProviderName[];
     /** History that could not be read whole; ANALYSIS_HISTORY_NOT_RECORDED when there is none. */
     warnings: string[];
 }

package/dist/run/display.d.ts

@@ -1,6 +1,6 @@
 import type { RunOutcome } from "./bundle.js";
 import type { ExecutionFailure } from "./judge.js";
-import { type RunLiveness } from "./status.js";
+import { type RunAnalysisPhase, type RunLiveness } from "./status.js";
 /** The states a run is shown in. */
 export type RunDisplayState = "running" | "interrupted" | "passed" | "failed" | "blocked" | "timed_out" | "no_verdict" | "dry_run" | "unknown";
 /** A run as a surface shows it. */
@@ -31,6 +31,11 @@ export interface RunDisplayFacts {
  * show as passed.
  */
 export declare function runDisplay(facts: RunDisplayFacts): RunDisplay;
+/**
+ * What a surface shows after a run's display while its automatic analysis runs, or once that
+ * analysis's process stopped without an end: the run's own result stays its participants'.
+ */
+export declare function analysisPhaseLabel(phase: RunAnalysisPhase | undefined): string | undefined;
 /** A state in words: "passed", "timed out", "no verdict". */
 export declare function runDisplayLabel(state: RunDisplayState): string;
 /** What bundleDisplayFacts reads from run.json; a listing reads it from an unchecked file. */

package/dist/run/display.js

@@ -61,6 +61,17 @@ export function runDisplay(facts) {
         return shown(facts.mode === "dry-run" ? "dry_run" : "no_verdict");
     return shown("unknown");
 }
+/**
+ * What a surface shows after a run's display while its automatic analysis runs, or once that
+ * analysis's process stopped without an end: the run's own result stays its participants'.
+ */
+export function analysisPhaseLabel(phase) {
+    if (phase?.state === "running")
+        return "analyzing";
+    if (phase?.state === "stopped")
+        return "analysis stopped";
+    return undefined;
+}
 /** A state in words: "passed", "timed out", "no verdict". */
 export function runDisplayLabel(state) {
     return LABELS[state];

package/dist/run/host-suspension.js

@@ -19,7 +19,10 @@ export const systemHostClock = {
 };
 /**
  * A wall-clock gap between two heartbeats this long or longer is a suspension. A shorter one is
- * most likely a busy event loop.
+ * most likely a busy event loop. It is twice RUN_STATUS_STALE_MS (src/run/status.ts) on purpose:
+ * that threshold is a reader's guess, made without the writer, so it errs early; this one is the
+ * writer's own record, and a route blames participant failures on it, so it errs late. A pause of
+ * 15 to 30 s reads as stale while it lasts and leaves no suspension on record.
  */
 const HOST_SUSPENSION_MIN_MS = 30_000;
 /** Run `onTick` every `intervalMs` on `clock`, and record each gap of 30 s or more. */

package/dist/run/preflight-receipts.d.ts

@@ -1,16 +1,7 @@
+import { type ProcessOwner } from "./process-owner.js";
 import { type PreparedSelectedOutputDirectory } from "./contained-output.js";
-/**
- * Who opened a journal. A pid means nothing outside its host and pid namespace (a probe in a
- * container writing to a bind-mounted checkout has a pid the host cannot see), so reclaim trusts
- * a dead pid only when both match its own.
- */
-interface PreflightOwner {
-    hostname: string;
-    /** `pid:[inode]` from /proc/self/ns/pid, where the platform has one. */
-    pidNamespace?: string;
-    pid: number;
-    /** Start time in clock ticks since boot (/proc/<pid>/stat), which tells a reused pid apart. */
-    startTicks?: string;
+/** Who opened a journal (src/run/process-owner.ts), when, and for how long. */
+interface PreflightOwner extends ProcessOwner {
     createdAt: string;
     /** The probe's server-side timeout. */
     leaseMs: number;