humanish 0.107.0 → 0.109.0

package/dist/observer/static.js

@@ -1,369 +0,0 @@
-import { constants as fsConstants } from "node:fs";
-import { createServer } from "node:http";
-import { lstat, open, realpath } from "node:fs/promises";
-import path from "node:path";
-import { buildArtifactSecurityHeaders } from "./http.js";
-// Loopback-only host for the Observer static server. We never bind 0.0.0.0:
-// the Observer surfaces local run evidence and must stay reachable only from
-// the machine that owns the run bundle.
-export const OBSERVER_STATIC_HOST = "127.0.0.1";
-// Minimal extension -> content-type map. Kept dependency-free (no `mime`
-// package) because the Observer ships a small, known set of asset kinds.
-const CONTENT_TYPES = {
-    ".html": "text/html; charset=utf-8",
-    ".htm": "text/html; charset=utf-8",
-    ".js": "text/javascript; charset=utf-8",
-    ".mjs": "text/javascript; charset=utf-8",
-    ".css": "text/css; charset=utf-8",
-    ".json": "application/json; charset=utf-8",
-    ".map": "application/json; charset=utf-8",
-    ".svg": "image/svg+xml",
-    ".png": "image/png",
-    ".jpg": "image/jpeg",
-    ".jpeg": "image/jpeg",
-    ".webp": "image/webp",
-    ".gif": "image/gif",
-    ".ico": "image/x-icon",
-    ".md": "text/markdown; charset=utf-8",
-    ".ndjson": "application/x-ndjson; charset=utf-8",
-    ".txt": "text/plain; charset=utf-8",
-    ".woff": "font/woff",
-    ".woff2": "font/woff2",
-};
-export function observerStaticContentType(filePath) {
-    return CONTENT_TYPES[path.extname(filePath).toLowerCase()] ?? "application/octet-stream";
-}
-/**
- * Resolve, guard, and serve a single static request from `root`. Never throws:
- * any unexpected failure is reported as a 500 so the connection always closes.
- * Exported directly so the security guards can be unit-tested without binding a
- * socket.
- */
-export async function respondToObserverStaticRequest(options, request, response) {
-    applySecurityHeaders(response);
-    try {
-        const root = await pinStaticRoot(options.root);
-        await respondToPinnedObserverStaticRequest(root, options, request, response);
-    }
-    catch {
-        if (response.headersSent) {
-            response.end();
-            return;
-        }
-        writeText(response, 500, "Observer request failed");
-    }
-}
-async function respondToPinnedObserverStaticRequest(root, options, request, response) {
-    applySecurityHeaders(response);
-    const indexRelative = options.indexPath ?? "index.html";
-    try {
-        await assertPinnedStaticRoot(root);
-        const method = request.method ?? "GET";
-        if (method !== "GET" && method !== "HEAD") {
-            writeText(response, 405, "Method Not Allowed");
-            return;
-        }
-        let pathname;
-        try {
-            pathname = new URL(request.url ?? "/", `http://${OBSERVER_STATIC_HOST}`).pathname;
-        }
-        catch {
-            writeText(response, 400, "Bad Request");
-            return;
-        }
-        if (pathname === "/" && options.redirectRootTo) {
-            const location = `/${options.redirectRootTo.replace(/^\/+/, "")}`;
-            response.writeHead(302, {
-                location,
-                "cache-control": "no-store",
-                "content-length": "0",
-            });
-            response.end();
-            return;
-        }
-        let decoded;
-        try {
-            decoded = decodeURIComponent(pathname);
-        }
-        catch {
-            writeText(response, 400, "Bad Request");
-            return;
-        }
-        // Reject embedded NUL bytes outright rather than letting them reach the fs.
-        if (decoded.includes("\0")) {
-            writeText(response, 400, "Bad Request");
-            return;
-        }
-        let relative = decoded.replace(/^\/+/, "");
-        if (relative === "" || relative.endsWith("/")) {
-            relative = `${relative}${indexRelative}`;
-        }
-        const target = path.resolve(root.physicalPath, relative);
-        if (!isPathInside(root.physicalPath, target)) {
-            writeText(response, 403, "Forbidden");
-            return;
-        }
-        let info;
-        try {
-            info = await lstat(target);
-        }
-        catch {
-            writeText(response, 404, "Not Found");
-            return;
-        }
-        if (info.isSymbolicLink()) {
-            writeText(response, 403, "Forbidden");
-            return;
-        }
-        let filePath = target;
-        if (info.isDirectory()) {
-            filePath = path.resolve(target, indexRelative);
-            if (!isPathInside(root.physicalPath, filePath)) {
-                writeText(response, 403, "Forbidden");
-                return;
-            }
-        }
-        const rawBody = await readContainedRegularFile(root, filePath);
-        const body = rawBody ? recordedObserverStaticBody(filePath, rawBody) : null;
-        if (!body) {
-            writeText(response, 404, "Not Found");
-            return;
-        }
-        response.writeHead(200, {
-            "cache-control": "no-store",
-            "content-type": observerStaticContentType(filePath),
-            "content-length": String(body.byteLength),
-        });
-        if (method === "HEAD") {
-            response.end();
-            return;
-        }
-        response.end(body);
-    }
-    catch {
-        if (response.headersSent) {
-            response.end();
-            return;
-        }
-        writeText(response, 500, "Observer request failed");
-    }
-}
-function applySecurityHeaders(response) {
-    for (const [name, value] of Object.entries(buildArtifactSecurityHeaders()))
-        response.setHeader(name, value);
-}
-/** Static serving is recorded evidence. Neither JSON files nor inline HTML snapshots
- * can carry a live process observation or grant provider-origin access. */
-function recordedObserverStaticBody(filePath, body) {
-    const strip = (text) => {
-        try {
-            const data = JSON.parse(text);
-            if (!data ||
-                typeof data !== "object" ||
-                Array.isArray(data) ||
-                data.schema !== "humanish.observer-data.v1")
-                return null;
-            const projection = data;
-            delete projection.runtime;
-            if (Array.isArray(projection.streams)) {
-                for (const stream of projection.streams) {
-                    if (!stream || typeof stream !== "object" || Array.isArray(stream))
-                        continue;
-                    const embed = stream.embed;
-                    if (embed && typeof embed === "object" && !Array.isArray(embed))
-                        delete embed.runtimeDesktop;
-                }
-            }
-            return JSON.stringify(projection)
-                .replace(/</g, "\\u003c")
-                .replace(/>/g, "\\u003e")
-                .replace(/&/g, "\\u0026");
-        }
-        catch {
-            return null;
-        }
-    };
-    if (path.basename(filePath) === "observer-data.json") {
-        const stripped = strip(body.toString("utf8"));
-        return stripped === null ? body : Buffer.from(stripped);
-    }
-    if (/\.html?$/i.test(filePath)) {
-        const html = body.toString("utf8");
-        // Identify Observer JSON by its schema, not an attribute spelling: HTML permits
-        // encoded ids and '>' inside quoted attributes. Other scripts remain byte-identical.
-        const sanitized = html.replace(/(<script\b(?:[^>"']|"[^"]*"|'[^']*')*>)([\s\S]*?)(<\/script\s*>)/gi, (match, start, json, end) => {
-            const stripped = strip(json);
-            return stripped === null ? match : `${start}${stripped}${end}`;
-        });
-        return sanitized === html ? body : Buffer.from(sanitized);
-    }
-    return body;
-}
-async function readContainedRegularFile(root, filePathInput) {
-    const filePath = path.resolve(filePathInput);
-    if (!isPathInside(root.physicalPath, filePath))
-        return null;
-    try {
-        await assertPinnedStaticRoot(root);
-        const expectedStats = await inspectContainedStaticFile(root, filePath);
-        if (!expectedStats) {
-            return null;
-        }
-        const handle = await open(filePath, fsConstants.O_RDONLY | fsConstants.O_NOFOLLOW);
-        try {
-            const openedStats = await handle.stat({ bigint: true });
-            if (!openedStats.isFile() ||
-                openedStats.nlink !== 1n ||
-                openedStats.dev !== expectedStats.dev ||
-                openedStats.ino !== expectedStats.ino) {
-                return null;
-            }
-            const recheckedStats = await inspectContainedStaticFile(root, filePath);
-            if (!recheckedStats ||
-                recheckedStats.dev !== expectedStats.dev ||
-                recheckedStats.ino !== expectedStats.ino) {
-                return null;
-            }
-            await assertPinnedStaticRoot(root);
-            const body = await handle.readFile();
-            await assertPinnedStaticRoot(root);
-            return body;
-        }
-        finally {
-            await handle.close();
-        }
-    }
-    catch {
-        return null;
-    }
-}
-export function createObserverStaticHandler(options) {
-    let rootPromise;
-    return (request, response) => {
-        applySecurityHeaders(response);
-        rootPromise ??= pinStaticRoot(options.root);
-        void rootPromise
-            .then((root) => respondToPinnedObserverStaticRequest(root, options, request, response))
-            .catch(() => {
-            if (response.headersSent) {
-                response.end();
-                return;
-            }
-            writeText(response, 500, "Observer request failed");
-        });
-    };
-}
-export async function serveObserverStatic(options) {
-    const entryPath = options.entryPath?.replace(/^\/+/, "") ?? "";
-    const handlerOptions = {
-        root: options.root,
-        ...(options.indexPath === undefined ? {} : { indexPath: options.indexPath }),
-        ...(entryPath ? { redirectRootTo: entryPath } : {}),
-    };
-    const root = await pinStaticRoot(options.root);
-    const handler = (request, response) => {
-        void respondToPinnedObserverStaticRequest(root, handlerOptions, request, response);
-    };
-    const server = createServer(handler);
-    const port = await listen(server, options.port ?? 0);
-    return {
-        url: `http://${OBSERVER_STATIC_HOST}:${port}/${entryPath}`,
-        port,
-        host: OBSERVER_STATIC_HOST,
-        close: () => closeServer(server),
-    };
-}
-function writeText(response, status, message) {
-    const body = `${message}\n`;
-    response.writeHead(status, {
-        "cache-control": "no-store",
-        "content-type": "text/plain; charset=utf-8",
-        "content-length": String(Buffer.byteLength(body)),
-    });
-    response.end(body);
-}
-function isPathInside(root, candidate) {
-    const relative = path.relative(root, candidate);
-    return (relative === "" ||
-        (relative !== ".." && !relative.startsWith(`..${path.sep}`) && !path.isAbsolute(relative)));
-}
-async function inspectContainedStaticFile(root, filePath) {
-    const relative = path.relative(root.physicalPath, filePath);
-    if (!relative ||
-        relative === ".." ||
-        relative.startsWith(`..${path.sep}`) ||
-        path.isAbsolute(relative)) {
-        return null;
-    }
-    const segments = relative.split(path.sep).filter(Boolean);
-    let current = root.physicalPath;
-    let fileIdentity = null;
-    for (const [index, segment] of segments.entries()) {
-        current = path.join(current, segment);
-        const stats = await lstat(current, { bigint: true });
-        if (stats.isSymbolicLink())
-            return null;
-        if (index < segments.length - 1) {
-            if (!stats.isDirectory())
-                return null;
-        }
-        else {
-            if (!stats.isFile() || stats.nlink !== 1n)
-                return null;
-            fileIdentity = { dev: stats.dev, ino: stats.ino };
-        }
-    }
-    if ((await realpath(filePath)) !== filePath)
-        return null;
-    return fileIdentity;
-}
-async function pinStaticRoot(rootInput) {
-    const physicalPath = await realpath(path.resolve(rootInput));
-    const stats = await lstat(physicalPath, { bigint: true });
-    if (stats.isSymbolicLink() || !stats.isDirectory()) {
-        throw new Error("Observer static roots must be physical directories.");
-    }
-    return Object.freeze({
-        birthtimeNs: stats.birthtimeNs,
-        dev: stats.dev,
-        ino: stats.ino,
-        physicalPath,
-    });
-}
-async function assertPinnedStaticRoot(root) {
-    const stats = await lstat(root.physicalPath, { bigint: true });
-    if (stats.isSymbolicLink() ||
-        !stats.isDirectory() ||
-        stats.birthtimeNs !== root.birthtimeNs ||
-        stats.dev !== root.dev ||
-        stats.ino !== root.ino ||
-        (await realpath(root.physicalPath)) !== root.physicalPath) {
-        throw new Error("Observer static root identity changed.");
-    }
-}
-function listen(server, port) {
-    return new Promise((resolve, reject) => {
-        server.once("error", reject);
-        server.listen(port, OBSERVER_STATIC_HOST, () => {
-            server.off("error", reject);
-            const address = server.address();
-            if (!address || typeof address === "string") {
-                reject(new Error("Observer static server did not bind to a TCP port."));
-                return;
-            }
-            resolve(address.port);
-        });
-    });
-}
-function closeServer(server) {
-    return new Promise((resolve, reject) => {
-        server.close((error) => {
-            if (error) {
-                reject(error);
-            }
-            else {
-                resolve();
-            }
-        });
-    });
-}

package/dist/run-lab.d.ts

@@ -1,112 +0,0 @@
-import type { LocalVmInput } from "./routes/computer-use/types.js";
-import { type LateScorer } from "./lab/route-inputs.js";
-import { type LabRoute } from "./lab/plan.js";
-import type { LabDeps } from "./lab/lab-deps.js";
-import type { RunLabDriving, RunLabHomes } from "./lab/run-lab-homes.js";
-import { type LabConfig } from "./lab/types.js";
-import type { ObserverResult } from "./observer/render.js";
-import { type CuaActorLabResult } from "./routes/computer-use/types.js";
-import { type ScriptedBrowserLabResult } from "./routes/scripted/types.js";
-import { type ConcurrentSharedWorldLabResult } from "./routes/shared-world/types.js";
-import { type TerminalProductLabResult } from "./routes/terminal/types.js";
-import { type RunScorerProvenance } from "./run/bundle.js";
-import { type RunResult } from "./run/results.js";
-import { type RunLabProvenance } from "./run/status.js";
-/**
- * Runs a lab on its route. The options are checked against the route and mapped into the route's
- * hook bags before anything runs. Each route closes the run it started on every exit through its
- * own run scope (`src/run/run.ts`).
- */
-export declare function runLab(config: LabConfig, options: InternalRunLabOptions, deps?: LabDeps): Promise<LabOutcome>;
-/**
- * runLab as the package exports it (`src/index.ts`): the public options only. A JavaScript caller
- * that passes a field RunLabOptions no longer has is refused in the route's own result envelope
- * before anything runs.
- */
-export declare function runPackageLab(config: LabConfig, options: RunLabOptions): Promise<LabOutcome>;
-/** A lab planned once: the route's refusal, or the run of its plan. */
-export type PreparedLab = {
-    readonly ok: false;
-    readonly outcome: LabOutcome;
-} | {
-    readonly ok: true;
-    /** Runs the plan. A scorer loaded after planning joins the run's hooks; it changes no plan. */
-    run(scorer?: LateScorer): Promise<LabOutcome>;
-};
-/**
- * Normalizes the options and plans the lab once, so a caller can present a refusal before it loads
- * anything the run needs. A local browser study's provider is bound first, so the plan is made with
- * it, and its desktop goes to the computer-use run as `localVm`; with inProcess the caller drives
- * the app in process and needs no desktop.
- */
-export declare function prepareLab(config: LabConfig, options: InternalRunLabOptions, deps?: LabDeps): Promise<PreparedLab>;
-/**
- * What a package caller passes to runLab: the run's settings and the typed homes (`RunLabHomes`,
- * `RunLabDriving`). Each wins over the config when provided.
- */
-export type RunLabOptions = RunLabBase & RunLabHomes & RunLabDriving;
-interface RunLabBase {
-    cwd: string;
-    runId?: string;
-    dryRun?: boolean;
-    open?: boolean;
-    /** Participant count override: preview participants or computer-use desktops. */
-    count?: number;
-    /** CUA fan-out only: create a new run for failed/selected participants from a prior run. */
-    rerun?: {
-        sourceRunId: string;
-        participantIds?: string[];
-    };
-    onObserverReady?: (observer: ObserverResult & {
-        ok: true;
-    }) => Promise<void> | void;
-}
-/** runLab's options inside the package: the public ones plus what only the CLI and tests set. */
-export type InternalRunLabOptions = RunLabOptions & RunLabInternals;
-interface RunLabInternals {
-    /**
-     * Which manifest this run came from (#455). planLab puts it on the plan, and the route reads
-     * plan.lab for the run's status record and bundle. Absent for a library caller that passes a
-     * LabConfig directly; that run records no lab.
-     */
-    lab?: RunLabProvenance;
-    /**
-     * CONFIG-DECLARED scorer provenance (#316), forwarded alongside whichever hooks bag carries the
-     * loaded scorer. Its presence is the "declared" marker the terminal route reads to flip a
-     * status:"fail" verdict; the browser routes stamp it as evidence (they already flip). Core-computed
-     * (path + digest), never adopter-supplied; absent for library callers.
-     */
-    scorerProvenance?: RunScorerProvenance;
-    /** The local VM study's desktop, analysis gate and signal, for a local browser lab. */
-    localVm?: LocalVmInput;
-}
-/** A run's result and the route it ran on. */
-interface RouteOutcome<R extends LabRoute, T> {
-    route: R;
-    result: T;
-}
-export type LabOutcome = RouteOutcome<"preview", RunResult> | RouteOutcome<"computer-use", CuaActorLabResult> | RouteOutcome<"scripted", ScriptedBrowserLabResult> | RouteOutcome<"terminal", TerminalProductLabResult> | RouteOutcome<"shared-world", ConcurrentSharedWorldLabResult>;
-/**
- * A plan past its route's local checks that need no scorer: the refusal they returned, or the
- * route's run, which takes a scorer loaded after them.
- */
-export type AdmittedPlan<R extends LabRoute = LabRoute> = {
-    readonly ok: false;
-    readonly outcome: Extract<LabOutcome, {
-        route: R;
-    }>;
-} | {
-    readonly ok: true;
-    run(scorer?: LateScorer): Promise<Extract<LabOutcome, {
-        route: R;
-    }>>;
-};
-/** The result of a run on route `R`, the `result` of that route's `LabOutcome`. */
-export type LabResult<R extends LabRoute = LabRoute> = {
-    preview: RunResult;
-    "computer-use": CuaActorLabResult;
-    scripted: ScriptedBrowserLabResult;
-    terminal: TerminalProductLabResult;
-    "shared-world": ConcurrentSharedWorldLabResult;
-}[R];
-export {};

package/docs/architecture/comms-inbox.md

@@ -1,122 +0,0 @@
-# Participant inboxes
-
-This page describes local capture. For fresh hosted inboxes, see
-[real email receiving](real-email-receiving.md); that route has a separate
-parsed renderer, strict remote-asset blocking and private lease lifecycle.
-
-The catch captures application mail without sending it to an external recipient.
-humanish gives each participant an address and a matching
-`/inbox/for/<address-digest>` URL. The same address scope applies to list, message,
-plain view, latest-message and JSON routes. Going back from a missing message
-stays in that scope. An unknown scope is empty; it never falls back to all mail.
-A participant without an assigned address receives no inbox instruction.
-
-This works with separate participant worlds, shared worlds, and an external catch.
-Sharing an application world does not require sharing an inbox. If a lab deliberately
-assigns the same address to two participants, both see that address's mail. Generated
-addresses that collide after normalization are made distinct. A message addressed
-to several participants appears in each recipient's inbox and retains its actual
-To field.
-
-`/inbox` remains available and is labeled **Shared operator inbox**. Address digests
-are routing identifiers, not authentication credentials. The catch is study
-infrastructure, not a mailbox service with hostile-tenant isolation. Keep its network
-exposure appropriate for test mail. The read-only listener cannot expose the private
-`/deliveries` drain, even when supplied a valid drain token. The capture listener
-retains its existing optional bearer-token protection for that endpoint.
-
-A standalone catch tracks its generated files. Reusing its directory with a changed
-`--recipient` roster or an emptied delivery log removes obsolete message, latest and
-recipient routes; unrelated files are untouched.
-
-## Local browser studies
-
-Run a catch on the same host as the local study:
-
-```bash
-humanish comms catch --port 8025 --dir .humanish/mail-catch
-```
-
-Configure your **app's** email transport to send to `http://127.0.0.1:8025`
-using its supported HTTP send configuration, or add `--smtp-port 1025` and
-point its SMTP transport at `127.0.0.1:1025`. humanish does not change an
-already-running app's environment. No real mailbox-provider credentials are
-needed. This captures mail sent by that app; it does not receive arbitrary
-internet email.
-
-Add this to an existing local `app-url` lab:
-
-```yaml
-comms:
-  email:
-    external:
-      catchBaseUrl: http://127.0.0.1:8025
-```
-
-Then run `humanish doctor --lab <lab>` and `humanish run <lab>`. Omit
-`recipients` to assign an address per participant automatically, or declare explicit
-`{ lane, address }` entries for an existing roster. The participant receives its
-address and inbox URL in its mission. Verification links keep their original
-app origin; ensure they target the loopback app port selected by the lab.
-
-Each local desktop forwards a separate host-owned read-only proxy for its
-assigned recipient. Other recipient routes, the operator inbox, mail sends and
-the private delivery drain are unavailable through that proxy. The study closes
-these proxies with its desktops and leaves your catch running. Host-side
-collection uses the existing digest-only comms evidence. Supported captured
-images and explicit unavailable-image placeholders work as described below.
-
-The local path supports captured email only. Provider-backed real receiving
-retains its separate hosted-route and management-credential requirements.
-
-## Existing external catches
-
-Upgrade the humanish installation that runs `humanish comms catch` and **restart that
-catch process**, as well as upgrading the installation that starts the study. Updating
-only the study client leaves an older catch without participant routes.
-
-Before allocating participants, the client checks `/health` on both `catchBaseUrl`
-and a distinct `inboxBaseUrl`. Each must return the normal service marker and
-`capabilities: ["recipient-inbox-v1", ...]`. Missing, malformed or older responses
-fail admission with an upgrade/restart instruction. Existing email capture endpoints
-and unscoped operator URLs remain available; their payload contracts are unchanged.
-
-## Captured and remote images
-
-The SMTP catch preserves MIME parts with a Content-ID when they contain PNG, JPEG,
-GIF or WebP bytes. The generic `/emails` payload can also carry runtime-only
-`inlineImages` entries with `contentId`, `contentType` and `base64`. Provider-specific
-attachment fields are not converted; unsupported or missing CID references show an
-explicit unavailable-image placeholder instead of pretending capture succeeded.
-
-Captured images are limited to 12 entries, 1 MiB each and 2 MiB total. The renderer
-checks canonical base64 and the declared raster format's signature before creating a
-data URL. This is not a full image decoder; malformed raster content can still fail
-in the browser. Inline data URLs receive the same per-image checks. SVG, arbitrary
-attachment URLs and local paths are not fetched or converted.
-
-HTTP(S) images remain browser loads with `no-referrer`. humanish does not fetch or
-proxy them server-side. Relative image URLs use the existing declared origin-rewrite
-map when available; otherwise they receive an explicit placeholder. Remote URLs that
-return errors retain the browser's alt-text fallback. The renderer does not claim to
-repair a dead URL. The inbox retains `script-src 'none'` and the existing HTML
-neutralization and origin-rewrite protections.
-
-Raw mail and image bytes remain runtime catch data. Persisted comms evidence remains
-digest-only; adding image capture does not add raw attachments to the run artifact.
-
-## Reproduce the contract
-
-```bash
-pnpm exec vitest run tests/comms/ tests/substrates/local/captured-inbox.test.ts
-pnpm exec tsx scripts/comms-inbox-proof.ts
-```
-
-The browser proof starts owned loopback HTTP, read-only inbox and SMTP listeners,
-sends fictional multipart mail through the real MIME parser, and renders two recipient
-inboxes in Chromium at desktop and phone sizes. It checks decoded CID/data/remote
-images, unavailable sources, a genuine remote 404, recipient isolation across HTML
-and JSON, navigation, script blocking, referrer suppression, directory reuse and drain
-access. Screenshots and a machine-readable receipt are saved under the ignored
-`.humanish/comms-inbox-proof/` directory. It uses no external email delivery, paid model
-calls or hosted desktop, and makes no claim about those providers.

package/docs/architecture/desktop-recording.md

@@ -1,80 +0,0 @@
-# Optional desktop recording
-
-humanish keeps screenshots, actions, participant feedback and analysis by default.
-For continuous playback, opt into a desktop video:
-
-```yaml
-execution:
-  desktop:
-    recording: { audio: true }
-```
-
-Set `audio: false` for screen-only video. Omit `recording` to keep the lightweight
-snapshot recording. This applies to independent computer-use desktop participants on
-local Firecracker and E2B; scripted-browser, shared-world and in-process executors
-do not consume this setting and reject it before execution.
-
-Recording does not enable a camera, speech synthesis or speech recognition.
-Those remain separate [participant media](participant-media.md) options. With
-audio enabled, microphone input and speaker output are mixed into one AAC track.
-`audioSources` identifies the capture points feeding that mix, not separate
-retained tracks. The microphone can be silent when speech is not configured.
-A recorded microphone signal proves what was offered to the browser, not what
-another person received. Confirm reciprocal delivery from the other
-participant's evidence.
-
-## Capture and playback
-
-The desktop runs FFmpeg against its X display. MP4 carries H.264 video and optional
-AAC audio. Recording stops and streams to the run directory before desktop cleanup.
-Both providers use the same encoding settings and artifact metadata. Video encoding
-uses the capture input’s microsecond time base, preserving closely spaced captures
-and their offsets rather than rounding them to the nominal frame interval.
-Explicit variable-frame-rate output preserves gaps without filling them with
-duplicate frames across the supported FFmpeg versions. The recording
-mix disables playback rewinds to avoid the null sink's initial two-second buffer. The local
-runtime transfers one bounded file over its existing owner connection; E2B uses
-the SDK's streaming file download. Participant tools cannot request arbitrary files.
-
-Local recording uses the existing optional media runtime archive. This keeps the
-browser-only download unchanged, but the optional archive also contains speech
-assets even when speech is disabled. Recording alone does not start Whisper or
-text-to-speech. E2B's stock desktop already has the recording dependencies; a custom
-template must provide compatible FFmpeg, X11 and, for audio, PulseAudio tools.
-
-Observer uses the existing study clock to play the selected participant's video.
-Scrubbing, opening a participant and returning to the grid preserve study time.
-The grid continues to show lightweight captures; only the selected participant
-has audible playback. Outside the retained media interval, Observer shows that
-video is unavailable rather than extending its coverage. Old screenshot-only runs
-continue to work.
-
-Capture still begins after device and transport startup. An audio track can contain
-silence before a cold source delivers sound; early dispatch of speech or playback
-does not itself prove audible capture. Preserve these offsets when reviewing early
-events. The startup correction does not reconstruct missing frames or audio in
-existing files. Variable guest execution stalls can still leave frame gaps; the
-recorded timestamps preserve those gaps. A regularly timestamped video can also
-show an unchanged screen while the application stalls. Visual/audio event timing
-depends on source delivery and guest execution; timestamp precision does not
-guarantee simultaneous delivery. See #854 for the remaining investigation.
-
-The file and its measured interval are recorded in `streams[].recording` and a
-`recording` artifact entry. A recorder failure warns and preserves screenshots,
-actions and feedback; it does not fail an otherwise useful participant. Incomplete
-but playable media is labeled partial. Forced VM loss may leave no retrievable
-video. Analysis continues to use the existing screenshot and text evidence; it
-does not inspect the MP4.
-
-## Local evidence and exports
-
-Video and audio are raw local evidence. `policies.redactScreenshots` does not redact
-them, and verification keeps a run with continuous media `local_only`. The recorder
-has a 128 MiB per-participant file limit; a retained size-limited recording is partial.
-Encoding consumes additional CPU, memory and disk, so snapshots remain the default.
-
-`humanish export --local-only` produces the existing portable HTML with screenshots
-and text, excludes continuous media and displays that exclusion. Open the original
-run through `humanish watch` or `humanish serve` to play its video. Redacted bundle
-export does not redact video/audio and rejects these runs. There is no new portable
-video format or automatic audio/video redaction in this feature.