humanish 0.145.0 → 0.147.0

package/dist/remote/runner.d.ts

@@ -13,16 +13,36 @@ export interface Runner {
     readonly shell: Shell;
 }
 export declare function runnerOf(sandbox: E2BDesktopSandbox): Runner;
+/** A study file read here, for the same place in the runner's project. */
+export interface ProjectFile {
+    /** Relative to the project, with `/` separators. */
+    path: string;
+    bytes: Uint8Array;
+}
 /**
- * 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.
+ * Read each project-relative file in `files`, and every file under each directory in `directories`
+ * that exists here, for upload to the runner. Read before any sandbox exists, so a refusal costs
+ * nothing.
  */
-export declare function installHumanish(runner: Runner, tarball: Uint8Array, peers: readonly string[]): Promise<string>;
+export declare function readProject(cwd: string, files: readonly string[], directories: readonly string[]): Promise<ProjectFile[]>;
+/** What a runner is set up with. */
+export interface RunnerSetup {
+    /** This machine's humanish as an npm tarball; it may still be packing when setup starts. */
+    tarball: Promise<Uint8Array>;
+    /**
+     * The npm specs its package depends on, from its own package.json, and the provider SDK its
+     * participants need, as name@version.
+     */
+    dependencies: readonly string[];
+    project: readonly ProjectFile[];
+}
 /**
- * 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.
+ * Install Node, this humanish's dependencies and this humanish in the runner, and upload the
+ * study's files. Node's download starts at once and the dependencies install as soon as it is
+ * there, while the tarball packs and uploads beside them; the tarball is then unpacked in place,
+ * so no install waits for the pack. Returns the installed version.
  */
-export declare function uploadProject(runner: Runner, cwd: string, files: readonly string[], directories: readonly string[]): Promise<number>;
+export declare function setUpRunner(runner: Runner, setup: RunnerSetup): Promise<string>;
 /** What the runner's run is started with. */
 export interface RemoteRunStart {
     /** The study file, relative to the project. */
@@ -51,19 +71,28 @@ export interface RemoteRunState {
     /** 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. */
+/**
+ * How the runner's run is going. The runner checks its run every 0.2 s for up to `waitMs` and
+ * answers as soon as it differs from `seen`: a new state, a result, or its process ending. One
+ * command answers each wait, so the launcher learns of a change within a check of it.
+ */
+export declare function waitForRemoteRun(runner: Runner, runId: string, seen: {
+    state: string | undefined;
+    alive: boolean;
+}, waitMs: number): Promise<RemoteRunState>;
+/** One file of the runner's run directory: its path in the directory, its size and its sha256. */
 export interface RemoteFile {
     path: string;
+    size: number;
     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.
+ * The regular files of the runner's run directory, with their sizes and 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[];
+/** sha256sum lines, `<hex>  ./<path>`, with paths relative to the directory. */
+export declare function parseDigests(output: string): Omit<RemoteFile, "size">[];
 /**
  * The screenshots and recordings of the runner's run that have not changed for `settledSeconds`,
  * with their sizes. A run writes each of them once, so one that has settled can be copied while
@@ -80,8 +109,12 @@ export declare function parseSizes(output: string): {
 }[];
 /** The bytes of one file of the runner's run directory, as they are now. */
 export declare function readRemoteBytes(runner: Runner, runId: string, file: string): Promise<Uint8Array>;
-/** 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>;
+/**
+ * Read `files` of the runner's run directory and hand each to `take`, checked against its listed
+ * digest. The files go in batches, each joined into one runner file and read back in one request,
+ * so a batch costs two round trips whatever its number of files.
+ */
+export declare function readRemoteFiles(runner: Runner, runId: string, files: readonly RemoteFile[], take: (file: RemoteFile, bytes: Uint8Array) => Promise<void>): Promise<void>;
 /**
  * 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.

package/dist/remote/runner.js

@@ -46,47 +46,88 @@ async function runOrFail(runner, step, command, timeoutMs) {
     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.
+ * Read each project-relative file in `files`, and every file under each directory in `directories`
+ * that exists here, for upload to the runner. Read before any sandbox exists, so a refusal costs
+ * nothing.
  */
-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) {
+export async function readProject(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);
+    const read = [];
     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));
+        read.push({ path: file, bytes: await readFile(real) });
     }
-    return all.size;
+    return read;
+}
+/** Study files written to the runner at once. */
+const UPLOAD_CONCURRENCY = 8;
+/** The npm project in the runner that holds this humanish and its dependencies. */
+const RUNNER_APP = `${RUNNER_STATE}/app`;
+/**
+ * Install Node, this humanish's dependencies and this humanish in the runner, and upload the
+ * study's files. Node's download starts at once and the dependencies install as soon as it is
+ * there, while the tarball packs and uploads beside them; the tarball is then unpacked in place,
+ * so no install waits for the pack. Returns the installed version.
+ */
+export async function setUpRunner(runner, setup) {
+    const npm = `export PATH="$HOME/${RUNNER_STATE}/node/bin:$PATH"`;
+    const dependencies = [
+        "set -eu",
+        `mkdir -p "$HOME/${RUNNER_APP}"`,
+        `cd "$HOME/${RUNNER_APP}"`,
+        npm,
+        `printf '{"private":true}\\n' > package.json`,
+        `npm install --no-save --no-package-lock --no-fund --no-audit --update-notifier=false --loglevel=error ${setup.dependencies.map(shellQuote).join(" ")}`,
+    ].join("\n");
+    const steps = [
+        runOrFail(runner, "Installing Node", nodeInstallScript(), 600_000).then(() => runOrFail(runner, "Installing humanish's dependencies", `bash -c ${shellQuote(dependencies)}`, 600_000)),
+        setup.tarball.then((bytes) => runner.shell.writeFile(`${RUNNER_STATE}/humanish.tgz`, toArrayBuffer(bytes))),
+        uploadProject(runner, setup.project),
+    ];
+    await Promise.all(steps);
+    // npm's own install would resolve every dependency again. Unpacked beside them, the package
+    // finds them as an installed one does, and its bin goes where npm puts a global one.
+    const unpack = [
+        "set -eu",
+        `cd "$HOME/${RUNNER_STATE}"`,
+        npm,
+        `package="$HOME/${RUNNER_APP}/node_modules/humanish"`,
+        'mkdir -p "$package" && tar -xzf humanish.tgz --strip-components=1 -C "$package"',
+        `bin="$package/$(node -p 'require(process.argv[1]).bin.humanish' "$package/package.json")"`,
+        'chmod +x "$bin" && ln -sf "$bin" node/bin/humanish',
+        `node -p 'require(process.argv[1]).version' "$package/package.json"`,
+    ].join("\n");
+    const result = await runOrFail(runner, "Installing humanish", `bash -c ${shellQuote(unpack)}`, 600_000);
+    return result.stdout.trim().split("\n").at(-1) ?? "";
+}
+/** Download Node into the runner, check it against its published sha256 and extract it. */
+function nodeInstallScript() {
+    const { version, sha256 } = NODE;
+    const script = [
+        "set -eu",
+        `mkdir -p "$HOME/${RUNNER_STATE}"`,
+        `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",
+    ].join("\n");
+    return `bash -c ${shellQuote(script)}`;
+}
+async function uploadProject(runner, files) {
+    for (let at = 0; at < files.length; at += UPLOAD_CONCURRENCY)
+        await Promise.all(files
+            .slice(at, at + UPLOAD_CONCURRENCY)
+            .map((file) => runner.shell.writeFile(`${RUNNER_PROJECT}/${file.path}`, toArrayBuffer(file.bytes))));
 }
 async function filesUnder(cwd, directory) {
     let entries;
@@ -141,32 +182,64 @@ export async function startRemoteRun(runner, start) {
     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,
+/** How often the runner checks its run while the launcher waits on it. */
+const WAIT_CHECK_SECONDS = 0.2;
+const SECTION = "--- humanish ";
+/**
+ * How the runner's run is going. The runner checks its run every 0.2 s for up to `waitMs` and
+ * answers as soon as it differs from `seen`: a new state, a result, or its process ending. One
+ * command answers each wait, so the launcher learns of a change within a check of it.
+ */
+export async function waitForRemoteRun(runner, runId, seen, waitMs) {
+    const status = `$HOME/${RUNNER_PROJECT}/.humanish/runs/${runId}/status.json`;
+    const result = `$HOME/${RUNNER_STATE}/result.json`;
+    const checks = Math.max(1, Math.ceil(waitMs / 1000 / WAIT_CHECK_SECONDS));
+    // The first "state" in status.json is the run's own; its outcome and analysis come after it.
+    const script = [
+        `status="${status}" result="${result}"`,
+        `state() { grep -m1 -o '"state": *"[^"]*"' "$status" 2>/dev/null | sed 's/.*"\\([^"]*\\)"$/\\1/'; }`,
+        "alive() { if pgrep -f '[h]umanish watch' >/dev/null; then echo 1; else echo 0; fi; }",
+        `i=0; while [ "$i" -lt ${checks} ]; do`,
+        '  [ -s "$result" ] && break',
+        `  [ "$(state)" != ${shellQuote(seen.state ?? "")} ] && break`,
+        `  [ "$(alive)" != ${seen.alive ? 1 : 0} ] && break`,
+        `  sleep ${WAIT_CHECK_SECONDS}; i=$((i + 1))`,
+        "done",
+        `echo "${SECTION}alive $(alive)"`,
+        `echo "${SECTION}status"; cat "$status" 2>/dev/null`,
+        `echo; echo "${SECTION}result"; cat "$result" 2>/dev/null`,
+        `echo; echo "${SECTION}err"; tail -c 2000 "$HOME/${RUNNER_STATE}/watch.err" 2>/dev/null`,
+        "exit 0",
+    ].join("\n");
+    const answer = await runner.shell.run(`bash -c ${shellQuote(script)}`, {
+        timeoutMs: waitMs + 30_000,
     });
+    if (answer.exitCode !== 0)
+        throw new RunnerCommandError("Reading the run", answer);
+    const sections = new Map();
+    let name;
+    for (const line of answer.stdout.split("\n")) {
+        if (line.startsWith(SECTION)) {
+            const [key = "", ...rest] = line.slice(SECTION.length).split(" ");
+            name = key;
+            sections.set(key, rest.join(" "));
+        }
+        else if (name !== undefined)
+            sections.set(name, `${sections.get(name)}${line}\n`);
+    }
+    const state = parseJson(sections.get("status"));
+    const ended = parseJson(sections.get("result"));
     return {
-        ...(typeof status?.state === "string" ? { state: status.state } : {}),
-        ...(typeof result?.exitCode === "number"
-            ? { result: { exitCode: result.exitCode, result: result.result } }
+        ...(typeof state?.state === "string" ? { state: state.state } : {}),
+        ...(typeof ended?.exitCode === "number"
+            ? { result: { exitCode: ended.exitCode, result: ended.result } }
             : {}),
-        alive: alive.exitCode === 0,
-        errTail: tailOf(err.stdout),
+        alive: sections.get("alive")?.trim() === "1",
+        errTail: tailOf(sections.get("err")),
     };
 }
 function parseJson(text) {
-    if (text === undefined)
+    if (text === undefined || text.trim() === "")
         return undefined;
     try {
         const value = JSON.parse(text);
@@ -179,18 +252,28 @@ function parseJson(text) {
     }
 }
 /**
- * The regular files of the runner's run directory and their digests. Refuses a directory that holds
- * a link, which a run never writes.
+ * The regular files of the runner's run directory, with their sizes and 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);
+    const listed = await runOrFail(runner, "Listing the run", `cd ${shellQuote(dir)} && find . ! -type f ! -type d -print -quit && echo "${SECTION}sizes" && find . -type f -printf '%s %p\\n' && echo "${SECTION}digests" && find . -type f -print0 | xargs -0 -r sha256sum`, 300_000);
+    const [links = "", rest = ""] = listed.stdout.split(`${SECTION}sizes\n`);
+    if (links.trim() !== "")
+        throw new Error(`The runner's run directory holds something other than files and folders (${tailOf(links)}), so it is not copied.`);
+    const [sizes = "", digests = ""] = rest.split(`${SECTION}digests\n`);
+    const size = new Map();
+    for (const line of sizes.split("\n")) {
+        const match = /^(\d+) \.\/(.+)$/.exec(line);
+        if (match !== null)
+            size.set(match[2], Number(match[1]));
+    }
+    return parseDigests(digests).flatMap((file) => {
+        const bytes = size.get(file.path);
+        return bytes === undefined ? [] : [{ ...file, size: bytes }];
+    });
 }
-/** sha256sum lines, `<hex>  ./<path>`, as RemoteFiles with paths relative to the directory. */
+/** sha256sum lines, `<hex>  ./<path>`, with paths relative to the directory. */
 export function parseDigests(output) {
     const files = [];
     for (const line of output.split("\n")) {
@@ -224,22 +307,74 @@ export function parseSizes(output) {
 }
 /** The bytes of one file of the runner's run directory, as they are now. */
 export async function readRemoteBytes(runner, runId, file) {
+    return readRunnerBytes(runner, `${RUNNER_PROJECT}/.humanish/runs/${runId}/${file}`);
+}
+/** The bytes of a runner file, by its path under the sandbox user's home. */
+async function readRunnerBytes(runner, 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}`, { format: "stream", requestTimeoutMs: 300_000 });
+    const stream = await read.call(runner.sandbox.files, file, {
+        format: "stream",
+        requestTimeoutMs: 300_000,
+    });
     const parts = [];
     for await (const chunk of stream)
         parts.push(chunk);
     return Buffer.concat(parts);
 }
-/** The bytes of one file of the runner's run directory, checked against its listed digest. */
-export async function readRemoteFile(runner, runId, file) {
-    const bytes = await readRemoteBytes(runner, runId, file.path);
-    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;
+/** The most bytes one batch of a copy joins into one runner file. */
+const COPY_BATCH_BYTES = 64 * 1024 * 1024;
+/** The most files one batch of a copy names on its command line. */
+const COPY_BATCH_FILES = 200;
+/** The runner file a batch is joined into, under the sandbox user's home. */
+const COPY_FILE = `${RUNNER_STATE}/copy.bin`;
+/**
+ * Read `files` of the runner's run directory and hand each to `take`, checked against its listed
+ * digest. The files go in batches, each joined into one runner file and read back in one request,
+ * so a batch costs two round trips whatever its number of files.
+ */
+export async function readRemoteFiles(runner, runId, files, take) {
+    const dir = `${RUNNER_PROJECT}/.humanish/runs/${runId}`;
+    for (const batch of batches(files)) {
+        // Each file's end offset in the joined file, so a file that changed size since the listing
+        // still splits where it ends; its digest then refuses it.
+        const joined = await runOrFail(runner, "Copying the run", `cd ${shellQuote(dir)} && : > "$HOME/${COPY_FILE}" && for f in ${batch.map((file) => shellQuote(file.path)).join(" ")}; do cat -- "$f" >> "$HOME/${COPY_FILE}" && wc -c < "$HOME/${COPY_FILE}" || exit 1; done`, 300_000);
+        const ends = joined.stdout.trim().split("\n").map(Number);
+        const bytes = await readRunnerBytes(runner, COPY_FILE);
+        if (ends.length !== batch.length || ends.at(-1) !== bytes.byteLength)
+            throw new Error("A batch of the run's files arrived incomplete from the runner.");
+        let start = 0;
+        for (const [index, file] of batch.entries()) {
+            const part = bytes.subarray(start, ends[index]);
+            start = ends[index];
+            if (createHash("sha256").update(part).digest("hex") !== file.sha256)
+                throw new Error(`${file.path} changed or arrived damaged while it was copied from the runner.`);
+            await take(file, part);
+        }
+    }
+    if (files.length > 0)
+        await runner.shell
+            .run(`rm -f "$HOME/${COPY_FILE}"`, { timeoutMs: 30_000 })
+            .catch(() => undefined);
+}
+function batches(files) {
+    const all = [];
+    let batch = [];
+    let bytes = 0;
+    for (const file of files) {
+        if (batch.length > 0 &&
+            (bytes + file.size > COPY_BATCH_BYTES || batch.length >= COPY_BATCH_FILES)) {
+            all.push(batch);
+            batch = [];
+            bytes = 0;
+        }
+        batch.push(file);
+        bytes += file.size;
+    }
+    if (batch.length > 0)
+        all.push(batch);
+    return all;
 }
 /**
  * Ask the runner's run to stop as a signal would, so it reclaims its participants and ends. The

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

@@ -5,10 +5,20 @@ import { participantInbox, planParticipantComms } from "./comms.js";
 import { participantBrowserStateObserver } from "./fidelity.js";
 import { networkHooks, planParticipantNetwork } from "./network.js";
 import { acquireParticipantDesktop, placeParticipantFiles, provisionParticipantSubject, verifyParticipantScreen, } from "./prepare.js";
-import { keepParticipantScreenOn, openParticipantSurface, startParticipantMedia, startParticipantStream, } from "./start.js";
+import { keepParticipantScreenOn, openParticipantSurface, recordsSound, startParticipantRecording, startParticipantSpeech, startParticipantStream, } from "./start.js";
 import { desktopEvidenceOf, newParticipantState } from "./state.js";
 import { finishE2BDesktop } from "./teardown.js";
 import { participantServeUrl } from "../types.js";
+/**
+ * Wait for every step, then throw the first failure in list order. No step is still running when
+ * preparation fails and teardown starts, and the failure named is the one the serial order named.
+ */
+async function settleInOrder(steps) {
+    const settled = await Promise.allSettled(steps);
+    const failed = settled.find((step) => step.status === "rejected");
+    if (failed !== undefined)
+        throw failed.reason;
+}
 export function createE2BParticipantDesktop(spec, deps, warnings) {
     const targetUrl = spec.planned.targetUrl ?? deps.appUrl;
     const state = newParticipantState(spec);
@@ -42,15 +52,45 @@ export function createE2BParticipantDesktop(spec, deps, warnings) {
             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.
-        await verifyParticipantScreen(ctx, state, desktop);
-        await placeParticipantFiles(ctx, state, desktop);
-        await provisionParticipantSubject(ctx, state, desktop);
-        await startParticipantMedia(ctx, state, desktop);
-        await openParticipantSurface(ctx, state, desktop);
+        const { kind } = ctx.deps.subject;
+        if (kind === "clone" || kind === "local-tree" || kind === "desktop-cli") {
+            // A subject provisioned in the sandbox takes minutes and may read the participant's files
+            // as it starts, so these steps run in order. The device claim is verified in the sandbox,
+            // and fails closed.
+            await verifyParticipantScreen(ctx, state, desktop);
+            await placeParticipantFiles(ctx, state, desktop);
+            await provisionParticipantSubject(ctx, state, desktop);
+            await startParticipantSurface(desktop);
+        }
+        else {
+            // An app that is only opened: Chrome takes seconds to start, so the screen check and the
+            // file copy run beside it. The files only need to land before the session.
+            await settleInOrder([
+                verifyParticipantScreen(ctx, state, desktop),
+                placeParticipantFiles(ctx, state, desktop),
+                startParticipantSurface(desktop),
+            ]);
+        }
         await keepParticipantScreenOn(ctx, desktop);
         prepared = true;
     }
+    /**
+     * Start speech and the recording, and open the browser or terminal. Chrome is launched in the
+     * sound env of speech or an audible recording, so those start before it; a silent recording
+     * starts beside it. Either way the recording is running before the session starts.
+     */
+    async function startParticipantSurface(desktop) {
+        await startParticipantSpeech(ctx, state, desktop);
+        if (recordsSound(ctx)) {
+            await startParticipantRecording(ctx, state, desktop);
+            await openParticipantSurface(ctx, state, desktop);
+            return;
+        }
+        await settleInOrder([
+            openParticipantSurface(ctx, state, desktop),
+            startParticipantRecording(ctx, state, desktop),
+        ]);
+    }
     async function openSession() {
         const { desktop, allocation } = state;
         if (!prepared || !desktop || !allocation || opened || finalization)

package/dist/routes/computer-use/e2b-desktop/prepare.d.ts

@@ -16,8 +16,10 @@ export declare function acquireParticipantDesktop(ctx: E2BParticipantContext, st
 export declare function verifyParticipantScreen(ctx: E2BParticipantContext, state: E2BParticipantState, desktop: E2BDesktopSandbox): Promise<void>;
 /**
  * Copy the participant's files (participants[].files) into its home folder and confirm each one's
- * size there, before the subject and the browser start. A file that does not land whole fails the
- * participant before its first turn. The state records each confirmed file as it lands.
+ * size there, before a provisioned subject starts and before the session. For an app that is only
+ * opened it runs while the browser starts: the browser reads the folder only when the participant
+ * opens a file chooser. A file that does not land whole fails the participant before its first
+ * turn. The state records each confirmed file as it lands.
  */
 export declare function placeParticipantFiles(ctx: E2BParticipantContext, state: E2BParticipantState, desktop: E2BDesktopSandbox): Promise<void>;
 /** Install a desktop CLI, or clone or unpack the subject and serve it, in the sandbox. */

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

@@ -158,8 +158,10 @@ export async function verifyParticipantScreen(ctx, state, desktop) {
 }
 /**
  * Copy the participant's files (participants[].files) into its home folder and confirm each one's
- * size there, before the subject and the browser start. A file that does not land whole fails the
- * participant before its first turn. The state records each confirmed file as it lands.
+ * size there, before a provisioned subject starts and before the session. For an app that is only
+ * opened it runs while the browser starts: the browser reads the folder only when the participant
+ * opens a file chooser. A file that does not land whole fails the participant before its first
+ * turn. The state records each confirmed file as it lands.
  */
 export async function placeParticipantFiles(ctx, state, desktop) {
     const { spec, deps } = ctx;

package/dist/routes/computer-use/e2b-desktop/start.d.ts

@@ -1,7 +1,15 @@
 import type { E2BDesktopSandbox } from "../../../substrates/e2b/sdk.js";
 import type { E2BParticipantContext, E2BParticipantState } from "./state.js";
-/** Start the declared speech worker and screen recording. A recording that cannot start is a warning. */
-export declare function startParticipantMedia(ctx: E2BParticipantContext, state: E2BParticipantState, desktop: E2BDesktopSandbox): Promise<void>;
+/** Start the declared speech worker. Chrome is launched in its sound env, so it starts first. */
+export declare function startParticipantSpeech(ctx: E2BParticipantContext, state: E2BParticipantState, desktop: E2BDesktopSandbox): Promise<void>;
+/**
+ * Whether the study records the desktop's sound. An audible recording runs its own sound server
+ * unless speech already did, and Chrome is launched in that server's env, so the recording starts
+ * before Chrome. A silent recording needs nothing from Chrome and starts beside it.
+ */
+export declare function recordsSound(ctx: E2BParticipantContext): boolean;
+/** Start the declared screen recording. A recording that cannot start is a warning. */
+export declare function startParticipantRecording(ctx: E2BParticipantContext, state: E2BParticipantState, desktop: E2BDesktopSandbox): Promise<void>;
 /**
  * Open what the participant sees: the browser at the target, with any declared camera and mobile
  * fidelity, or a terminal window on the desktop-cli route. A participant with a time zone sees the
@@ -11,10 +19,10 @@ export declare function openParticipantSurface(ctx: E2BParticipantContext, state
 /**
  * Turn the desktop's screen saver off, so the screen stays on while the participant waits without
  * input. The XFCE session sets the screen saver's timeout in its first seconds, and the last write
- * wins. Nothing waits for those writes: this runs after the browser or terminal has opened and the
- * desktop has waited DESKTOP_SETTLE_MS, and on 16 fresh desktops the last write came within 2.5 s
- * of a command sent as soon as the desktop was created. A screen saver that cannot be turned off
- * is a warning.
+ * wins. Nothing waits for those writes: this runs after a Chromium page has loaded, which needs
+ * DevTools to answer first (4.8 s or more after launch on live desktops), or after the fixed 8 s
+ * wait, and on 16 fresh desktops the last write came within 2.5 s of a command sent as soon as the
+ * desktop was created. A screen saver that cannot be turned off is a warning.
  */
 export declare function keepParticipantScreenOn(ctx: E2BParticipantContext, desktop: E2BDesktopSandbox): Promise<void>;
 /**