humanish 0.141.0 → 0.142.0

package/dist/remote/launch.d.ts

@@ -0,0 +1,53 @@
+import { type PreparedRunArtifactPaths } from "../run/paths.js";
+import type { RemotePlan } from "./plan.js";
+import { type Runner } from "./runner.js";
+/** What following a remote run needs from its caller: the project, its env and a progress line. */
+export interface RemoteContext {
+    cwd: string;
+    env: Readonly<Record<string, string | undefined>>;
+    /** Progress lines for a person, on stderr. */
+    say: (line: string) => void;
+}
+export interface RemoteLaunch extends RemoteContext {
+    /** The study file, relative to cwd. */
+    study: string;
+    remote: RemotePlan;
+    /** Local Observer port; 0 picks a free one. */
+    port: number;
+}
+/** What a remote run ended as, for the command's result and exit code. */
+export interface RemoteOutcome {
+    runId: string;
+    exitCode: number;
+    /** The run's own result, as the runner's command wrote it. */
+    result?: unknown;
+    /** Why the remote run did not finish, when it did not. */
+    error?: string;
+    /** Left running on purpose: the terminal closed while the study went on. */
+    detached?: boolean;
+    files?: number;
+}
+/** Launch, follow and copy back one remote run. */
+export declare function launchRemoteRun(launch: RemoteLaunch): Promise<RemoteOutcome>;
+/** Follows the run until it ends, is stopped, detaches or stops answering. */
+export declare function followRemoteRun(args: {
+    launch: RemoteContext;
+    runner: Runner;
+    paths: PreparedRunArtifactPaths;
+    runId: string;
+    signals: Signals;
+    proxyUrl: string;
+}): Promise<RemoteOutcome>;
+/** Two sandbox journals as one: every line of each, in order, one per line. */
+export declare function joinJournals(...journals: string[]): string;
+export interface Signals {
+    readonly requested: "stop" | "detach" | undefined;
+    /** The exit code a local run gives for the stop signal received: 130 for SIGINT, 143 for SIGTERM. */
+    readonly exitCode: number;
+    dispose(): void;
+}
+/**
+ * Ctrl-C and SIGTERM stop the run, as they stop a local one. A closed terminal (SIGHUP) leaves it
+ * running; the runner ends it at its deadline.
+ */
+export declare function watchSignals(): Signals;

package/dist/remote/launch.js

@@ -0,0 +1,320 @@
+// `humanish run|watch <study> --remote`: run the study's own process in a runner sandbox on its
+// participants' provider, follow it from here, and copy the finished run back. This machine only
+// plans, launches and watches, so it may sleep or lose its network while the study goes on.
+import { execFile } from "node:child_process";
+import { randomBytes } from "node:crypto";
+import { mkdtemp, readFile, rm } from "node:fs/promises";
+import { tmpdir } from "node:os";
+import path from "node:path";
+import { fileURLToPath } from "node:url";
+import { promisify } from "node:util";
+import { readContainedRegularFile, writeContainedOutputFile } from "../run/contained-output.js";
+import { createRunArtifactPaths } from "../run/paths.js";
+import { reclaimRunSandboxes } from "../run/reclaim.js";
+import { pointLatestRunAt } from "../run/run.js";
+import { appendSandboxOwner, SANDBOX_RECEIPTS_ARTIFACT } from "../run/sandbox-receipts.js";
+import { loadE2BBaseModule } from "../substrates/e2b/base-module.js";
+import { e2bConnection } from "../substrates/e2b/connection.js";
+import { acquireE2BShellSandbox } from "../substrates/e2b/sandbox.js";
+import { loadModalShellModule } from "../substrates/modal/sandbox.js";
+import { serveObserverProxy } from "./observer-proxy.js";
+import { installHumanish, listRemoteRun, readRemoteFile, readRemoteRun, RUNNER_OBSERVER_PORT, runnerOf, startRemoteRun, stopRemoteRun, uploadProject, } from "./runner.js";
+/** How often the launcher reads the runner's run while it follows it. */
+const POLL_MS = 5_000;
+/** Reads in a row the runner may leave unanswered before the launcher gives it up. */
+const UNANSWERED_LIMIT = 24;
+/** How long the run has to write its status record after it is started. */
+const START_DEADLINE_MS = 3 * 60_000;
+/** How long a stopped run has to end and write its result. */
+const STOP_DEADLINE_MS = 2 * 60_000;
+/** Launch, follow and copy back one remote run. */
+export async function launchRemoteRun(launch) {
+    const { cwd, remote, say } = launch;
+    const runId = `cua-${new Date().toISOString().replace(/[:.]/g, "-")}-${randomBytes(4).toString("hex")}`;
+    const ownerKey = randomBytes(8).toString("hex");
+    const created = await createRunArtifactPaths(cwd, runId);
+    if (!created.ok)
+        throw new Error(`Run ${runId} already exists here.`);
+    const paths = created.paths;
+    // The participants carry the key the runner's run pins; this directory records it as an owner
+    // line, so reclaim here finds them. The runner itself carries this directory's own key, so the
+    // remote run, which reclaims by its key when it stops, never matches the sandbox it runs in.
+    const owned = await appendSandboxOwner(paths, { tool: "humanish", runId, runKey: ownerKey }, remote.provider);
+    if (!owned)
+        throw new Error(`Could not record run ${runId}'s owner tags in its run directory, so a later reclaim could not find its sandboxes. Nothing was created.`);
+    // Installed before the first sandbox exists, so a signal never ends this process while one is
+    // being created without a cleanup.
+    const signals = watchSignals();
+    let tarballDir;
+    let proxy;
+    try {
+        const tarball = await packThisHumanish();
+        tarballDir = tarball.dir;
+        const where = remote.provider === "modal" ? "a Modal sandbox" : "an E2B sandbox";
+        say(`Running this study on ${where} as run ${runId}; creating the runner.`);
+        const runner = runnerOf((await acquireRunner(launch, paths)).sandbox);
+        if (signals.requested !== undefined)
+            return await endRun(launch, runId, {
+                exitCode: signals.exitCode,
+                error: "stopped before the run started",
+            });
+        await writeRemoteRecord(paths, {
+            runId,
+            provider: remote.provider,
+            deadline: new Date(Date.now() + remote.runnerMs).toISOString(),
+        });
+        // Bound before the run starts, so a taken --port fails before any participant exists.
+        proxy = await serveObserverProxy(await runner.sandbox.portAccess(RUNNER_OBSERVER_PORT), launch.port);
+        const version = await installHumanish(runner, tarball.bytes, [await peerSpec(remote.provider)]);
+        say(`Installed humanish ${version} in the runner; uploading the study.`);
+        await uploadProject(runner, cwd, remote.uploads, remote.uploadDirectories);
+        if (signals.requested !== undefined)
+            return await endRun(launch, runId, {
+                exitCode: signals.exitCode,
+                error: "stopped before the run started",
+            });
+        await startRemoteRun(runner, {
+            study: launch.study,
+            runId,
+            ownerKey,
+            env: Object.fromEntries(remote.envNames.flatMap((name) => {
+                const value = launch.env[name];
+                return value === undefined || value === "" ? [] : [[name, value]];
+            })),
+        });
+        return await followRemoteRun({ launch, runner, paths, runId, signals, proxyUrl: proxy.url });
+    }
+    catch (error) {
+        await reclaimRunSandboxes(cwd, runId, { env: launch.env }).catch(() => undefined);
+        throw error;
+    }
+    finally {
+        signals.dispose();
+        await proxy?.close();
+        if (tarballDir !== undefined)
+            await rm(tarballDir, { recursive: true, force: true });
+    }
+}
+async function acquireRunner(launch, paths) {
+    const { provider, runnerMs } = launch.remote;
+    const module = provider === "modal" ? await loadModalShellModule(launch.env) : await loadE2BBaseModule();
+    // A Modal module takes its connection from launch.env and ignores these two.
+    const { apiKey = "", ...account } = e2bConnection(launch.env);
+    return acquireE2BShellSandbox({
+        module,
+        provider,
+        options: {
+            apiKey,
+            ...account,
+            timeoutMs: runnerMs,
+            metadata: { participantId: "runner" },
+            network: { allowPublicTraffic: false },
+        },
+        receipt: { root: paths, participantId: "runner" },
+    });
+}
+/** Follows the run until it ends, is stopped, detaches or stops answering. */
+export async function followRemoteRun(args) {
+    const { launch, runner, paths, runId, signals } = args;
+    const { say } = launch;
+    const copy = () => copyRunBack(runner, paths, runId);
+    let state;
+    let stopAt;
+    let unanswered = 0;
+    const startBy = Date.now() + START_DEADLINE_MS;
+    for (;;) {
+        const run = await readRemoteRun(runner, runId).catch(() => undefined);
+        unanswered = run === undefined ? unanswered + 1 : 0;
+        if (run?.state !== undefined && state === undefined) {
+            say(`Run ${runId} is running. Watch it live at ${args.proxyUrl}`);
+            say("Closing this terminal leaves the study running; Ctrl-C stops it.");
+        }
+        if (run?.state !== undefined && run.state !== state) {
+            state = run.state;
+            if (state !== "running")
+                say(`Run ${runId} is ${state}.`);
+        }
+        if (run?.result !== undefined) {
+            say("The run ended; copying its evidence back.");
+            const copied = await copy().then((files) => ({ files }), (error) => ({ error }));
+            // The run reclaimed its participants as it ended; only the runner is left, and it holds the
+            // only whole copy of the evidence until a copy succeeds.
+            if ("error" in copied && stopAt === undefined)
+                return {
+                    runId,
+                    exitCode: 2,
+                    error: `copying the evidence back failed (${message(copied.error)}). The runner keeps it until the deadline in its remote.json; stop it sooner with humanish reclaim --run ${runId}`,
+                };
+            return await endRun(launch, runId, {
+                // A run stopped from here exits as a local one does on that signal.
+                exitCode: stopAt === undefined ? run.result.exitCode : signals.exitCode,
+                result: run.result.result,
+                ...("files" in copied
+                    ? { files: copied.files }
+                    : { error: `copying the evidence back failed: ${message(copied.error)}` }),
+            });
+        }
+        if (signals.requested === "detach")
+            return { runId, exitCode: 0, detached: true };
+        if (signals.requested === "stop" && stopAt === undefined) {
+            say("Stopping the remote run; its participants are reclaimed before it ends.");
+            stopAt = Date.now() + STOP_DEADLINE_MS;
+            if (state === undefined)
+                return await endRun(launch, runId, {
+                    exitCode: signals.exitCode,
+                    error: "stopped before the run started",
+                });
+            await stopRemoteRun(runner).catch(() => undefined);
+        }
+        const ended = unanswered >= UNANSWERED_LIMIT
+            ? `the runner sandbox stopped answering for ${(UNANSWERED_LIMIT * POLL_MS) / 1000} s`
+            : run !== undefined && state !== undefined && !run.alive
+                ? stopAt === undefined
+                    ? `the run ended without a result: ${run.errTail || "no output"}`
+                    : "stopped"
+                : stopAt !== undefined && Date.now() > stopAt
+                    ? "stopped, and the run did not end in time"
+                    : state === undefined && Date.now() > startBy
+                        ? `the run did not start in the runner: ${run?.errTail || "no output"}`
+                        : undefined;
+        if (ended !== undefined) {
+            // Participants may still be running, so everything is reclaimed after whatever copies.
+            const copied = await copy().then((files) => ({ files }), (error) => ({ error }));
+            return await endRun(launch, runId, {
+                exitCode: stopAt === undefined ? 2 : signals.exitCode,
+                error: "files" in copied
+                    ? ended
+                    : `${ended}; copying its evidence back failed: ${message(copied.error)}`,
+                ...("files" in copied ? { files: copied.files } : {}),
+            });
+        }
+        await new Promise((resolve) => setTimeout(resolve, POLL_MS));
+    }
+}
+/**
+ * Copy every file of the runner's run directory into this machine's run directory, each checked
+ * against the digest the runner listed. The sandbox journal keeps this machine's lines (the
+ * runner's own receipt) and adds the runner's (its participants').
+ */
+async function copyRunBack(runner, paths, runId) {
+    const files = await listRemoteRun(runner, runId);
+    for (const file of files) {
+        if (file.path === "owner-key")
+            continue;
+        const bytes = await readRemoteFile(runner, runId, file);
+        if (file.path === SANDBOX_RECEIPTS_ARTIFACT) {
+            const local = await readContainedRegularFile(paths, file.path, 16 * 1024 * 1024);
+            const mine = local.status === "read" ? Buffer.from(local.bytes).toString("utf8") : "";
+            await writeContainedOutputFile(paths, file.path, joinJournals(mine, Buffer.from(bytes).toString("utf8")), "utf8");
+            continue;
+        }
+        await writeContainedOutputFile(paths, file.path, bytes);
+    }
+    await pointLatestRunAt(paths, runId);
+    return files.length;
+}
+/** Two sandbox journals as one: every line of each, in order, one per line. */
+export function joinJournals(...journals) {
+    const lines = journals
+        .flatMap((journal) => journal.split("\n"))
+        .filter((line) => line.trim() !== "");
+    return lines.length === 0 ? "" : `${lines.join("\n")}\n`;
+}
+/**
+ * Reclaim every sandbox of the run, by receipt and by its tags, and report a reclaim that did not
+ * come back clean as an error and a failing exit code.
+ */
+async function endRun(launch, runId, outcome) {
+    const reclaimed = await reclaimRunSandboxes(launch.cwd, runId, { env: launch.env }).then((result) => result.ok, () => false);
+    if (reclaimed)
+        return { runId, ...outcome };
+    return {
+        runId,
+        ...outcome,
+        exitCode: outcome.exitCode === 0 ? 2 : outcome.exitCode,
+        error: [
+            outcome.error,
+            `its sandboxes were not confirmed stopped; run humanish reclaim --run ${runId}`,
+        ]
+            .filter(Boolean)
+            .join("; "),
+    };
+}
+function message(error) {
+    return error instanceof Error ? error.message : String(error);
+}
+/**
+ * The run directory's record of where its run executes. It holds no credential and no raw sandbox
+ * id: the runner's id is in the sandbox journal with every other, as its `runner` receipt.
+ */
+async function writeRemoteRecord(paths, record) {
+    await writeContainedOutputFile(paths, "remote.json", `${JSON.stringify({ schema: "humanish.remote-run.v1", ...record }, null, 2)}\n`, "utf8");
+}
+/**
+ * Ctrl-C and SIGTERM stop the run, as they stop a local one. A closed terminal (SIGHUP) leaves it
+ * running; the runner ends it at its deadline.
+ */
+export function watchSignals() {
+    let requested;
+    let exitCode = 130;
+    const interrupt = () => {
+        requested ??= "stop";
+    };
+    const terminate = () => {
+        if (requested === undefined)
+            exitCode = 143;
+        requested ??= "stop";
+    };
+    const detach = () => {
+        requested ??= "detach";
+    };
+    process.on("SIGINT", interrupt);
+    process.on("SIGTERM", terminate);
+    process.on("SIGHUP", detach);
+    return {
+        get requested() {
+            return requested;
+        },
+        get exitCode() {
+            return exitCode;
+        },
+        dispose() {
+            process.off("SIGINT", interrupt);
+            process.off("SIGTERM", terminate);
+            process.off("SIGHUP", detach);
+        },
+    };
+}
+/**
+ * This machine's humanish as an npm tarball, so the runner runs exactly the same code. A run from
+ * source has no built package to pack.
+ */
+async function packThisHumanish() {
+    const here = fileURLToPath(import.meta.url);
+    const root = path.resolve(path.dirname(here), "..", "..");
+    if (path.relative(root, here).split(path.sep)[0] !== "dist")
+        throw new Error("A remote run installs this humanish in the runner, and a run from source has no built package. Run `pnpm build`, then `node dist/cli.js`, or use an installed humanish.");
+    const dir = await mkdtemp(path.join(tmpdir(), "humanish-pack-"));
+    const { stdout } = await promisify(execFile)("npm", ["pack", "--ignore-scripts", "--json", "--pack-destination", dir, root], { maxBuffer: 16 * 1024 * 1024 });
+    const [packed] = JSON.parse(stdout);
+    return { bytes: await readFile(path.join(dir, packed.filename)), dir };
+}
+/** The provider SDK the runner's participants need, at the version this machine has. */
+async function peerSpec(provider) {
+    const name = provider === "modal" ? "modal" : "@e2b/desktop";
+    try {
+        const entry = fileURLToPath(import.meta.resolve(name));
+        for (let dir = path.dirname(entry); dir !== path.dirname(dir); dir = path.dirname(dir)) {
+            const manifest = await readFile(path.join(dir, "package.json"), "utf8").catch(() => undefined);
+            if (manifest === undefined)
+                continue;
+            const parsed = JSON.parse(manifest);
+            if (parsed.name === name && parsed.version !== undefined)
+                return `${name}@${parsed.version}`;
+        }
+    }
+    catch {
+        // Not installed here, which planning already refused; the runner takes the latest.
+    }
+    return name;
+}

package/dist/remote/observer-proxy.d.ts

@@ -0,0 +1,11 @@
+import type { SandboxPortAccess } from "../substrates/e2b/sdk.js";
+export interface ObserverProxy {
+    readonly url: string;
+    close(): Promise<void>;
+}
+/**
+ * Serve `access` on 127.0.0.1:`port` (0 picks a free port). A request whose Host is not this
+ * loopback address is refused, so a page that rebinds a name to 127.0.0.1 cannot read the runner's
+ * Observer through it; a write must also come from this origin.
+ */
+export declare function serveObserverProxy(access: SandboxPortAccess, port: number): Promise<ObserverProxy>;

package/dist/remote/observer-proxy.js

@@ -0,0 +1,66 @@
+// The local end of watching a remote run: a server on 127.0.0.1 that forwards each request to the
+// runner's Observer through the provider's proxy, adding the credential the provider requires. The
+// credential stays in this process; the browser only ever talks to loopback.
+import { createServer, request as httpRequest, } from "node:http";
+import { request as httpsRequest } from "node:https";
+import { listenOnLoopback } from "../observer/listen.js";
+/** The hop-by-hop headers a proxy does not forward, and the ones this proxy sets itself. */
+const DROPPED = new Set(["host", "connection", "keep-alive", "upgrade", "proxy-authorization"]);
+/**
+ * Serve `access` on 127.0.0.1:`port` (0 picks a free port). A request whose Host is not this
+ * loopback address is refused, so a page that rebinds a name to 127.0.0.1 cannot read the runner's
+ * Observer through it; a write must also come from this origin.
+ */
+export async function serveObserverProxy(access, port) {
+    const target = new URL(access.url);
+    let origin = "";
+    const server = createServer((request, response) => {
+        if (!sameOrigin(request, origin)) {
+            response.writeHead(421, { "content-type": "text/plain; charset=utf-8" });
+            response.end("This address only serves 127.0.0.1.\n");
+            return;
+        }
+        forward(request, response, target, access.headers);
+    });
+    const bound = await listenOnLoopback(server, port);
+    origin = `127.0.0.1:${bound}`;
+    return {
+        url: `http://${origin}/`,
+        close: () => new Promise((resolve) => {
+            server.close(() => resolve());
+            server.closeAllConnections();
+        }),
+    };
+}
+function sameOrigin(request, host) {
+    const allowed = new Set([host, host.replace("127.0.0.1", "localhost")]);
+    if (!allowed.has(request.headers.host ?? ""))
+        return false;
+    if (request.method === "GET" || request.method === "HEAD")
+        return true;
+    const origin = request.headers.origin;
+    return origin !== undefined && [...allowed].some((name) => origin === `http://${name}`);
+}
+function forward(request, response, target, credentials) {
+    const headers = {};
+    for (const [name, value] of Object.entries(request.headers))
+        if (value !== undefined && !DROPPED.has(name))
+            headers[name] = value;
+    const secure = target.protocol === "https:";
+    const upstream = (secure ? httpsRequest : httpRequest)({
+        host: target.hostname,
+        port: target.port === "" ? (secure ? 443 : 80) : Number(target.port),
+        path: `${target.pathname.replace(/\/$/, "")}${request.url ?? "/"}`,
+        method: request.method,
+        headers: { ...headers, ...credentials, host: target.host },
+    }, (answer) => {
+        response.writeHead(answer.statusCode ?? 502, answer.headers);
+        answer.pipe(response);
+    });
+    upstream.on("error", () => {
+        if (!response.headersSent)
+            response.writeHead(502, { "content-type": "text/plain; charset=utf-8" });
+        response.end("The runner's Observer did not answer. The run may still be going; retry shortly.\n");
+    });
+    request.pipe(upstream);
+}

package/dist/remote/plan.d.ts

@@ -0,0 +1,35 @@
+import type { SandboxProviderId } from "../run/sandbox-receipts.js";
+import type { StudyConfig } from "../study/types.js";
+import type { StudyPlan } from "../study/plan-types.js";
+export interface RemotePlan {
+    readonly provider: SandboxProviderId;
+    /** The runner's lifetime: setup, the participants' last possible end, analysis and teardown. */
+    readonly runnerMs: number;
+    /** Paths relative to the project, uploaded to the same place in the runner's project. */
+    readonly uploads: readonly string[];
+    /** Directories, relative to the project, uploaded whole when they exist. */
+    readonly uploadDirectories: readonly string[];
+    /** The environment names the runner's run may receive, and nothing else. */
+    readonly envNames: readonly string[];
+}
+export type RemotePlanResult = {
+    ok: true;
+    plan: RemotePlan;
+} | {
+    ok: false;
+    reason: string;
+};
+/**
+ * The remote plan for `config`, whose live plan is `plan`, or why it cannot run remotely.
+ * `studyPath` is the study file, `cwd` the project it runs in. `ceilingMs` is the longest the
+ * provider keeps a sandbox.
+ */
+export declare function planRemoteRun(args: {
+    config: StudyConfig;
+    plan: StudyPlan;
+    cwd: string;
+    studyPath: string;
+    ceilingMs: number;
+    /** How many sandboxes the E2B account runs at once; the runner takes one of them. */
+    concurrentSandboxes: number;
+}): RemotePlanResult;

package/dist/remote/plan.js

@@ -0,0 +1,114 @@
+// Whether a study can run on a remote machine, the runner sandbox, and what the runner needs: how
+// long it must live, which files it must receive and which keys it may hold. A pure function of the
+// study and its plan, so a refusal happens before anything is created.
+import path from "node:path";
+import { keyNamesOf } from "../study/requirements.js";
+import { participantList } from "../study/study-fields.js";
+/** Time the runner needs before the study starts: create, Node and humanish install, uploads. */
+const RUNNER_SETUP_MS = 10 * 60_000;
+/** Time the runner needs after the study ends: syncing the run back and a margin. */
+const RUNNER_TEARDOWN_MS = 15 * 60_000;
+/** Settings the plan reads from the environment, which the remote run must read the same way. */
+const PLAN_SETTINGS = [
+    "HUMANISH_E2B_MAX_SANDBOX_MINUTES",
+    "HUMANISH_E2B_MAX_CONCURRENT_SANDBOXES",
+    "HUMANISH_CUA_MAX_CONCURRENCY",
+    "HUMANISH_E2B_REQUEST_TIMEOUT_MS",
+    "E2B_DOMAIN",
+];
+/** The connection names each provider's runner and participants are reached with. */
+const PROVIDER_KEYS = {
+    e2b: ["E2B_API_KEY"],
+    modal: ["MODAL_TOKEN_ID", "MODAL_TOKEN_SECRET", "MODAL_ENVIRONMENT"],
+};
+/**
+ * The remote plan for `config`, whose live plan is `plan`, or why it cannot run remotely.
+ * `studyPath` is the study file, `cwd` the project it runs in. `ceilingMs` is the longest the
+ * provider keeps a sandbox.
+ */
+export function planRemoteRun(args) {
+    const { config, plan, cwd } = args;
+    const refuse = (reason) => ({ ok: false, reason });
+    if (plan.route !== "computer-use")
+        return refuse(`a ${plan.route} study runs on this machine; only computer-use studies run remotely.`);
+    const runner = plan.runner;
+    if (runner.desktop !== "e2b-desktop")
+        return refuse("its participants use this machine's browser, so the study runs here.");
+    if (runner.brain.kind !== "openai")
+        return refuse("its participants are driven by an agent on this machine, which a remote run cannot reach.");
+    if (runner.subject.kind !== "app-url")
+        return refuse("its subject is built or served from this machine; only app-url subjects run remotely for now.");
+    if (servedHere(runner.subject.appUrl))
+        return refuse("its app URL points at this machine or a private network, which the runner cannot reach.");
+    if (plan.analysis?.config.provider === "codex")
+        return refuse("its analysis uses this machine's Codex login.");
+    if (config.review?.scorer !== undefined)
+        return refuse("it loads a scorer module, which does not run remotely yet.");
+    if (plan.rerun !== undefined)
+        return refuse("a rerun reads a run on this machine.");
+    const study = inside(cwd, args.studyPath);
+    if (study === undefined)
+        return refuse("the study file is outside the project directory.");
+    const files = [study];
+    for (const participant of participantList(config) ?? [])
+        for (const file of participant.files ?? []) {
+            const from = inside(cwd, path.resolve(path.dirname(args.studyPath), file.from));
+            if (from === undefined)
+                return refuse(`participant file ${file.from} is outside the project directory.`);
+            files.push(from);
+        }
+    if (runner.provider === "e2b" && plan.concurrency + 1 > args.concurrentSandboxes)
+        return refuse(`its ${plan.concurrency} participants at once and the runner need ${plan.concurrency + 1} E2B sandboxes at once, more than the ${args.concurrentSandboxes} your account runs. Lower execution.concurrency to ${args.concurrentSandboxes - 1}.`);
+    const runnerMs = runnerLifetimeMs(plan);
+    if (runnerMs > args.ceilingMs)
+        return refuse(`the study needs its runner for up to ${minutes(runnerMs)} minutes, longer than the ${minutes(args.ceilingMs)} minutes ${runner.provider === "modal" ? "Modal" : "E2B"} keeps a sandbox.`);
+    return {
+        ok: true,
+        plan: {
+            provider: runner.provider,
+            runnerMs,
+            uploads: [...new Set(files)],
+            uploadDirectories: ["humanish/personas", ".humanish/local/personas"],
+            envNames: [
+                ...new Set([...keyNamesOf(plan), ...PROVIDER_KEYS[runner.provider], ...PLAN_SETTINGS]),
+            ].sort(),
+        },
+    };
+}
+/** Setup, the participants' last possible end, the analysis's own limit and teardown. */
+function runnerLifetimeMs(plan) {
+    const analysisMs = plan.analysis?.config.timeoutMs ?? 0;
+    return RUNNER_SETUP_MS + plan.arrivals.lastEndMs + analysisMs + RUNNER_TEARDOWN_MS;
+}
+/** `target` relative to `cwd`, or undefined when it is outside it. */
+function inside(cwd, target) {
+    const relative = path.relative(path.resolve(cwd), path.resolve(cwd, target));
+    if (relative === "" || relative.startsWith("..") || path.isAbsolute(relative))
+        return undefined;
+    return relative.split(path.sep).join("/");
+}
+const minutes = (ms) => Math.ceil(ms / 60_000);
+/** Whether `appUrl` names loopback, a private address, or a name only this machine resolves. */
+function servedHere(appUrl) {
+    let host;
+    try {
+        host = new URL(appUrl).hostname.replace(/^\[|\]$/g, "").toLowerCase();
+    }
+    catch {
+        return true;
+    }
+    if (host === "localhost" || host.endsWith(".localhost") || host.endsWith(".local"))
+        return true;
+    if (host === "::1" || host.startsWith("fc") || host.startsWith("fd") || host.startsWith("fe80:"))
+        return host.includes(":");
+    const octets = host.split(".").map(Number);
+    if (octets.length !== 4 || octets.some((octet) => !Number.isInteger(octet)))
+        return false;
+    const [a, b] = octets;
+    return (a === 127 ||
+        a === 10 ||
+        a === 0 ||
+        (a === 172 && b >= 16 && b <= 31) ||
+        (a === 192 && b === 168) ||
+        (a === 169 && b === 254));
+}

package/dist/remote/reattach.d.ts

@@ -0,0 +1,17 @@
+import { type PreparedRunArtifactPaths } from "../run/paths.js";
+import { type SandboxProviderId } from "../run/sandbox-receipts.js";
+import { type RemoteContext, type RemoteOutcome } from "./launch.js";
+/** A run directory here whose run executes in a runner and has not been copied back. */
+export interface RemoteRunHere {
+    paths: PreparedRunArtifactPaths;
+    runId: string;
+    provider: SandboxProviderId;
+    runnerId: string;
+}
+/**
+ * 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 declare function remoteRunHere(cwd: string, runId: string): Promise<RemoteRunHere | undefined>;
+/** Reconnect to `run`'s runner, serve its Observer on 127.0.0.1:`port` and follow it to the end. */
+export declare function reattachRemoteRun(context: RemoteContext, run: RemoteRunHere, port: number): Promise<RemoteOutcome>;