humanish 0.140.0 → 0.141.0

package/dist/run/run.d.ts

@@ -3,6 +3,7 @@ import { type RunBundle } from "./bundle.js";
 import { type ExecutionFailure, type ExecutionOutcome, type OutcomePolicy } from "./judge.js";
 import { type PreparedRunArtifactPaths, type RunIdInUse } from "./paths.js";
 import { RunSecrets } from "./secrets.js";
+import { type RunStatusHandle } from "./status.js";
 import { type HostClock, type HostSuspension } from "./host-suspension.js";
 import type { RunStudyProvenance } from "./study-provenance.js";
 interface StartRunOptions {
@@ -170,7 +171,7 @@ export declare class FinishedRun {
     readonly runId: string;
     /** The paths created by startRun and validated at the start of `finish`. */
     readonly paths: PreparedRunArtifactPaths;
-    constructor(key: typeof issueKey, runId: string, paths: PreparedRunArtifactPaths, observer: ObserverTarget | undefined, outcome: RecordedOutcome, recordFailure: (failure: ExecutionFailure) => Promise<RecordedOutcome>, interrupted: () => boolean, participantsRan: () => boolean);
+    constructor(key: typeof issueKey, runId: string, paths: PreparedRunArtifactPaths, observer: ObserverTarget | undefined, outcome: RecordedOutcome, recordFailure: (failure: ExecutionFailure) => Promise<RecordedOutcome>, status: Pick<RunStatusHandle, "interrupted" | "beginAnalysis">, participantsRan: () => boolean);
     /**
      * A signal stopped this run's process: status.json and run.json record it `interrupted`. Read
      * when asked, since the signal can arrive after the bundle was published.
@@ -178,6 +179,12 @@ export declare class FinishedRun {
     get interrupted(): boolean;
     /** The route reported a participant's session started (Run.participantStarted). */
     get participantsRan(): boolean;
+    /**
+     * Automatic analysis of this run starts in this process: status.json records when, and its
+     * heartbeat runs again, so every surface can say the run is analyzing. Call the returned
+     * function with the analysis outcome's state when it ends. After an interrupt both do nothing.
+     */
+    beginAnalysis(): ReturnType<RunStatusHandle["beginAnalysis"]>;
     static isIssued(value: unknown): value is FinishedRun;
     /**
      * The run's ok and execution outcome as run.json records them: what the route passed to
@@ -195,12 +202,16 @@ export declare class FinishedRun {
 /**
  * Run `fn` as the lifetime of at most one run. When `fn` settles the scope closes synchronously,
  * so the scope and its run admit no further calls, even through references `fn` leaked into
- * timers or callbacks. It then waits for the calls it admitted and, unless the run finished,
- * finishes status.json with no outcome. The close cannot replace `fn`'s exception: admitted calls
- * are awaited settled and the status finish swallows its own write errors. `finished` is set only
+ * timers or callbacks. It then waits for the calls it admitted and, unless the run published,
+ * records status.json `interrupted` with reason `no-publish`: a run with no published bundle did
+ * not finish, so no surface shows it as passed or counts it in a study's durations. The close cannot replace `fn`'s exception: admitted calls
+ * are awaited settled and the status write swallows its own errors. `finished` is set only
  * when `Run.finish` resolved inside the scope, so a refusal cannot hand analysis another run.
  */
-export declare function runScope<T>(fn: (scope: RunScope) => Promise<T>): Promise<{
+export declare function runScope<T>(fn: (scope: RunScope) => Promise<T>, hooks?: {
+    /** The run exists: its directory and first status.json write landed. A throw is ignored. */
+    onStart?: (runId: string) => void;
+}): Promise<{
     result: T;
     finished: FinishedRun | undefined;
 }>;

package/dist/run/run.js

@@ -35,34 +35,42 @@ const issueKey = Symbol("FinishedRun");
 export class FinishedRun {
     #observer;
     #recordFailure;
-    #interrupted;
     #outcome;
     runId;
     /** The paths created by startRun and validated at the start of `finish`. */
     paths;
     #participantsRan;
-    constructor(key, runId, paths, observer, outcome, recordFailure, interrupted, participantsRan) {
+    #status;
+    constructor(key, runId, paths, observer, outcome, recordFailure, status, participantsRan) {
         if (key !== issueKey)
             throw new Error("Only Run.finish issues a FinishedRun.");
         this.runId = runId;
         this.paths = paths;
         this.#participantsRan = participantsRan;
+        this.#status = status;
         this.#observer = observer;
         this.#outcome = outcome;
         this.#recordFailure = recordFailure;
-        this.#interrupted = interrupted;
     }
     /**
      * A signal stopped this run's process: status.json and run.json record it `interrupted`. Read
      * when asked, since the signal can arrive after the bundle was published.
      */
     get interrupted() {
-        return this.#interrupted();
+        return this.#status.interrupted;
     }
     /** The route reported a participant's session started (Run.participantStarted). */
     get participantsRan() {
         return this.#participantsRan();
     }
+    /**
+     * Automatic analysis of this run starts in this process: status.json records when, and its
+     * heartbeat runs again, so every surface can say the run is analyzing. Call the returned
+     * function with the analysis outcome's state when it ends. After an interrupt both do nothing.
+     */
+    beginAnalysis() {
+        return this.#status.beginAnalysis();
+    }
     static isIssued(value) {
         return typeof value === "object" && value !== null && #observer in value;
     }
@@ -262,7 +270,7 @@ function runPublisher(args) {
             await writeBundleFiles(bundle, finishedOutcome(current), (publicBundle) => runStatus.restate(runStatusOutcome(publicBundle))).catch(() => undefined);
             return current;
         }));
-        return new FinishedRun(issueKey, runId, paths, observer, current, recordFailure, () => runStatus.interrupted, participantsRan);
+        return new FinishedRun(issueKey, runId, paths, observer, current, recordFailure, runStatus, participantsRan);
     };
     const interrupt = async (signal) => {
         interrupted = { state: "interrupted", ok: false, signal, at: new Date(now()).toISOString() };
@@ -287,12 +295,13 @@ function runPublisher(args) {
 /**
  * Run `fn` as the lifetime of at most one run. When `fn` settles the scope closes synchronously,
  * so the scope and its run admit no further calls, even through references `fn` leaked into
- * timers or callbacks. It then waits for the calls it admitted and, unless the run finished,
- * finishes status.json with no outcome. The close cannot replace `fn`'s exception: admitted calls
- * are awaited settled and the status finish swallows its own write errors. `finished` is set only
+ * timers or callbacks. It then waits for the calls it admitted and, unless the run published,
+ * records status.json `interrupted` with reason `no-publish`: a run with no published bundle did
+ * not finish, so no surface shows it as passed or counts it in a study's durations. The close cannot replace `fn`'s exception: admitted calls
+ * are awaited settled and the status write swallows its own errors. `finished` is set only
  * when `Run.finish` resolved inside the scope, so a refusal cannot hand analysis another run.
  */
-export async function runScope(fn) {
+export async function runScope(fn, hooks = {}) {
     let closed = false;
     let started = false;
     let status;
@@ -339,6 +348,12 @@ export async function runScope(fn) {
                 },
             });
             await runStatus.started;
+            try {
+                hooks.onStart?.(runId);
+            }
+            catch {
+                // An announcement cannot stop the run it announces.
+            }
             const run = openRun(options, runId, created.paths, runStatus);
             interruptBundle = run.interrupt;
             return { ok: true, run: run.run };
@@ -414,7 +429,7 @@ export async function runScope(fn) {
         }
         finally {
             if (finished === undefined)
-                await status?.finish();
+                await status?.abandon();
             unregister?.();
         }
     }

package/dist/run/status.d.ts

@@ -1,3 +1,4 @@
+import type { AutomaticAnalysisOutcome } from "../analysis/job.js";
 import type { RunBundle } from "./bundle.js";
 import { type RunStudyProvenance } from "./study-provenance.js";
 import { type PreparedOutputRoot } from "./contained-output.js";
@@ -10,11 +11,26 @@ export declare const RUN_STATUS_FILE = "status.json";
 export declare const RUN_STATUS_TOUCH_MS = 5000;
 /**
  * A `running` record whose `updatedAt` is older than this is interrupted, not alive: the process
- * died without finalizing (a dropped SSH, a killed terminal, a crash). Three touch intervals of
+ * died before the run ended (a dropped SSH, a killed terminal, a crash). Three touch intervals of
  * slack so an ordinary scheduling hiccup or a slow disk never mislabels a healthy run.
  */
 export declare const RUN_STATUS_STALE_MS: number;
 type RunStatusState = "running" | "finished" | "interrupted";
+/**
+ * Why a run is `interrupted` without a signal. `no-publish`: its process left the run without
+ * publishing a bundle, as a route that throws or returns a refusal after the run started does.
+ * `reclaimed`: `humanish reclaim` found its heartbeat stale and stopped its sandboxes.
+ */
+type RunInterruptReason = "no-publish" | "reclaimed";
+/** How automatic analysis ended, as its job records it. */
+type RunAnalysisEndState = AutomaticAnalysisOutcome["state"];
+/** Automatic analysis in the run's own process, after the run ended. */
+interface RunStatusAnalysis {
+    startedAt: string;
+    /** Absent while it runs, and on the record of a process that stopped during it. */
+    endedAt?: string;
+    state?: RunAnalysisEndState;
+}
 /** The signals the CLI's run handler records when it stops a run. */
 export type RunInterruptSignal = "SIGINT" | "SIGTERM" | "SIGHUP";
 /** The outcome summary a finalized record carries. Derived from the bundle; never authoritative. */
@@ -67,7 +83,14 @@ export interface RunStatusRecord {
     completedAt?: string;
     /** The signal that stopped the run, on an `interrupted` record. */
     signal?: RunInterruptSignal;
+    /** Why an `interrupted` record has no signal. */
+    reason?: RunInterruptReason;
     outcome?: RunStatusOutcome;
+    /**
+     * Set on a `finished` record when automatic analysis starts in the same process. While it
+     * runs, the heartbeat keeps `updatedAt` fresh; `completedAt` stays when the participants ended.
+     */
+    analysis?: RunStatusAnalysis;
 }
 export interface RunStatusHandle {
     /** Resolves once the initial record has landed on disk, and never rejects: a failed write is
@@ -75,7 +98,8 @@ export interface RunStatusHandle {
      *  it before a route can acquire a sandbox, so a run killed after its sandbox receipt lands
      *  still has a record to classify. */
     readonly started: Promise<void>;
-    /** Finalize: state `finished`, `completedAt`, and the derived outcome. Stops the cadence.
+    /** The run ended with a published bundle: state `finished`, `completedAt`, and the derived
+     *  outcome. Stops the cadence.
      *  Idempotent: a second call is a no-op, so a route with several exit paths is safe. */
     finish(outcome?: RunStatusOutcome): Promise<void>;
     /** After finish, replace the finished record's outcome with one read from a rewritten run.json,
@@ -88,6 +112,15 @@ export interface RunStatusHandle {
     interrupt(signal: RunInterruptSignal): Promise<boolean>;
     /** True from the moment `interrupt` accepts a signal, before its write lands. */
     readonly interrupted: boolean;
+    /** The run's scope closed without a publish: state `interrupted` with reason `no-publish`. A
+     *  no-op after finish or an interrupt, so it never overwrites a record that says more. */
+    abandon(): Promise<void>;
+    /**
+     * After finish, automatic analysis starts: `analysis.startedAt` is written and the heartbeat
+     * runs again until the returned function records the end and its state. Before finish or after
+     * an interrupt it writes nothing, and neither does the returned function.
+     */
+    beginAnalysis(): Promise<(state: RunAnalysisEndState) => Promise<void>>;
     /** The host suspensions the cadence saw until now, or until it stopped. */
     suspensions(): readonly HostSuspension[];
 }
@@ -114,6 +147,28 @@ export type RunLiveness = "running" | "interrupted" | "finished";
  * `nowMs` is passed in rather than read, so a classification is reproducible.
  */
 export declare function classifyRunStatus(record: Pick<RunStatusRecord, "state" | "updatedAt">, nowMs: number, staleMs?: number): RunLiveness;
+/** Automatic analysis as a status record shows it: running, ended, or stopped with its process. */
+export type RunAnalysisPhase = {
+    state: "running" | "stopped";
+    startedAt: string;
+} | {
+    state: "ended";
+    startedAt: string;
+    endedAt: string;
+    outcome?: RunAnalysisEndState;
+};
+/**
+ * The record's automatic analysis. `stopped` is an analysis with no end whose heartbeat went
+ * stale: the process ended during it. Undefined when the record has none, or one this version
+ * cannot read.
+ */
+export declare function runAnalysisPhase(record: Pick<RunStatusRecord, "updatedAt" | "analysis">, nowMs: number): RunAnalysisPhase | undefined;
+/**
+ * A `running` record whose heartbeat is stale and whose pid no process on this host holds: its
+ * owner is gone, so the run cannot still be writing. A live pid proves nothing either way (pids
+ * are reused), so such a record stays unconfirmed.
+ */
+export declare function runOwnerGone(record: Pick<RunStatusRecord, "state" | "pid" | "updatedAt">, nowMs: number, running?: (pid: number) => boolean): boolean;
 /** Shape guard for a record read off disk. Unknown extra fields are tolerated (additive contract). */
 export declare function isRunStatusRecord(value: unknown): value is RunStatusRecord;
 export {};

package/dist/run/status.js

@@ -20,7 +20,7 @@ export const RUN_STATUS_FILE = "status.json";
 export const RUN_STATUS_TOUCH_MS = 5_000;
 /**
  * A `running` record whose `updatedAt` is older than this is interrupted, not alive: the process
- * died without finalizing (a dropped SSH, a killed terminal, a crash). Three touch intervals of
+ * died before the run ended (a dropped SSH, a killed terminal, a crash). Three touch intervals of
  * slack so an ordinary scheduling hiccup or a slow disk never mislabels a healthy run.
  */
 export const RUN_STATUS_STALE_MS = RUN_STATUS_TOUCH_MS * 3;
@@ -132,6 +132,48 @@ export function beginRunStatus(runPaths, options) {
         get interrupted() {
             return interrupted;
         },
+        async abandon() {
+            if (finished)
+                return;
+            finished = true;
+            heartbeat.stop();
+            const completedAt = iso();
+            await write({
+                ...base,
+                state: "interrupted",
+                updatedAt: completedAt,
+                completedAt,
+                reason: "no-publish",
+            });
+        },
+        async beginAnalysis() {
+            const ended = async () => { };
+            if (finishedRecord === undefined || interrupted)
+                return ended;
+            const startedAt = iso();
+            finishedRecord = { ...finishedRecord, updatedAt: startedAt, analysis: { startedAt } };
+            await write(finishedRecord);
+            const analysisHeartbeat = startHeartbeat(clock, RUN_STATUS_TOUCH_MS, () => {
+                if (finishedRecord === undefined)
+                    return;
+                finishedRecord = { ...finishedRecord, updatedAt: iso() };
+                void write(finishedRecord);
+            });
+            let done = false;
+            return async (state) => {
+                if (done || finishedRecord?.analysis === undefined)
+                    return;
+                done = true;
+                analysisHeartbeat.stop();
+                const endedAt = iso();
+                finishedRecord = {
+                    ...finishedRecord,
+                    updatedAt: endedAt,
+                    analysis: { ...finishedRecord.analysis, endedAt, state },
+                };
+                await write(finishedRecord);
+            };
+        },
         suspensions: () => heartbeat.suspensions(),
     };
     return handle;
@@ -150,6 +192,50 @@ export function classifyRunStatus(record, nowMs, staleMs = RUN_STATUS_STALE_MS)
         return "interrupted";
     return nowMs - updated <= staleMs ? "running" : "interrupted";
 }
+/**
+ * The record's automatic analysis. `stopped` is an analysis with no end whose heartbeat went
+ * stale: the process ended during it. Undefined when the record has none, or one this version
+ * cannot read.
+ */
+export function runAnalysisPhase(record, nowMs) {
+    const analysis = record.analysis;
+    if (analysis === null || typeof analysis !== "object")
+        return undefined;
+    const { startedAt, endedAt, state } = analysis;
+    if (typeof startedAt !== "string" || !Number.isFinite(Date.parse(startedAt)))
+        return undefined;
+    if (typeof endedAt === "string")
+        return {
+            state: "ended",
+            startedAt,
+            endedAt,
+            ...(typeof state === "string" ? { outcome: state } : {}),
+        };
+    const updated = Date.parse(record.updatedAt);
+    return Number.isFinite(updated) && nowMs - updated <= RUN_STATUS_STALE_MS
+        ? { state: "running", startedAt }
+        : { state: "stopped", startedAt };
+}
+/** Whether `pid` names a process on this host. EPERM means one exists that this user cannot signal. */
+function processRunning(pid) {
+    try {
+        process.kill(pid, 0);
+        return true;
+    }
+    catch (error) {
+        return error.code === "EPERM";
+    }
+}
+/**
+ * A `running` record whose heartbeat is stale and whose pid no process on this host holds: its
+ * owner is gone, so the run cannot still be writing. A live pid proves nothing either way (pids
+ * are reused), so such a record stays unconfirmed.
+ */
+export function runOwnerGone(record, nowMs, running = processRunning) {
+    if (record.state !== "running" || classifyRunStatus(record, nowMs) === "running")
+        return false;
+    return record.pid !== process.pid && !running(record.pid);
+}
 /** Shape guard for a record read off disk. Unknown extra fields are tolerated (additive contract). */
 export function isRunStatusRecord(value) {
     if (value === null || typeof value !== "object")

package/dist/run/stored-runs.d.ts

@@ -1,5 +1,6 @@
 import { type ReviewSummary } from "./bundle.js";
 import { type RunDisplay } from "./display.js";
+import { type RunAnalysisPhase } from "./status.js";
 import { type VerifyResult } from "../verify/verify.js";
 declare const RUNS_SCHEMA = "humanish.runs-result.v1";
 export interface RunsResult {
@@ -13,6 +14,8 @@ export interface RunsResult {
         path: string;
         /** How the run reads (runDisplay in src/run/display.ts); absent when it has no readable run.json. */
         display?: RunDisplay;
+        /** The automatic analysis its own process started after the run ended, from status.json. */
+        analysis?: RunAnalysisPhase;
     }>;
     latest: string | null;
     error?: {

package/dist/run/stored-runs.js

@@ -6,7 +6,7 @@ import { assertPreparedSelectedOutputDirectory, bindExistingManagedHumanishOutpu
 import { RUN_BUNDLE_FILE } from "./bundle.js";
 import { isReviewSummary, isRunBundle, isRunOutcome } from "./bundle-shape.js";
 import { bundleDisplayFacts, displayedReview, runDisplay, } from "./display.js";
-import { RUN_STATUS_FILE } from "./status.js";
+import { isRunStatusRecord, RUN_STATUS_FILE, runAnalysisPhase, } from "./status.js";
 import { readLatest, readRunJsonIfExists, resolveRunPath, runJsonValue } from "./locate.js";
 import { withCuaReviewProvenance } from "./outcomes.js";
 import { displayedTraces, loadStreamTraces } from "./stream-trace.js";
@@ -106,10 +106,15 @@ async function listedRunDisplay(runPaths, bundle) {
     const displayed = displayedBundle(bundle);
     if (displayed === undefined)
         return {};
-    const status = displayed.outcome === undefined
-        ? runJsonValue(await readRunJsonIfExists(runPaths, RUN_STATUS_FILE))
+    const status = runJsonValue(await readRunJsonIfExists(runPaths, RUN_STATUS_FILE));
+    const analysis = isRunStatusRecord(status) && status.runId === displayed.runId
+        ? runAnalysisPhase(status, Date.now())
         : undefined;
-    return { display: runDisplay(bundleDisplayFacts(displayed, status)) };
+    return {
+        // A bundle with an outcome decides how the run ended; status.json only adds its analysis.
+        display: runDisplay(bundleDisplayFacts(displayed, displayed.outcome === undefined ? status : undefined)),
+        ...(analysis === undefined ? {} : { analysis }),
+    };
 }
 /** The fields runDisplay reads from an unchecked run.json; none when it does not name a run. */
 function displayedBundle(bundle) {

package/dist/study/run-study-events.d.ts

@@ -19,7 +19,8 @@ export type SetupTarget = {
     readonly participant: ParticipantRef;
 };
 /**
- * What a run reports while it runs. `plan` comes from computer use only; the other routes run from
+ * What a run reports while it runs. `run-started` comes from every route that records a run, once
+ * its run id exists. `plan` comes from computer use only; the other routes run from
  * the study plan but do not emit it. `subject-phase` comes from computer use (participant target)
  * and shared world (subject target).
  */
@@ -40,6 +41,11 @@ export type StudyEvent = {
     at: string;
     ok?: boolean;
     durationMs?: number;
+}
+/** The run's directory and status.json exist: `runId` names it from here on. */
+ | {
+    type: "run-started";
+    runId: string;
 } | {
     type: "analysis-started";
 } | {

package/dist/substrates/e2b/desktop-browser.js

@@ -5,6 +5,7 @@ import { failureTail } from "../../evidence/redaction.js";
 import { isHttpUrl } from "../../study/parse/subject.js";
 import { runDetachedStep } from "../detached.js";
 import { shellQuote } from "../shell.js";
+import { externalLinkHandlerSetup } from "./desktop-handoff.js";
 import { e2bShell } from "./shell.js";
 // Settle after opening the browser or the terminal, before the first screenshot: long enough for
 // a cold browser and page load to paint (2 s captured a blank desktop; the render needs 6-9 s).
@@ -210,7 +211,8 @@ extraChromiumFlags = [], environment) {
             `target_url=${shellQuote(targetUrl)}`,
             `browser_preference=${shellQuote(requestedBrowser)}`,
             "profile_dir=",
-            `chrome_preferences_json=${shellQuote(chromiumEvidenceProfilePreferencesJson())}`,
+            `chrome_preferences_json=${shellQuote(chromiumEvidenceProfilePreferencesJson(targetUrl))}`,
+            externalLinkHandlerSetup(),
             "prepare_profile() {",
             '  profile_dir="$(mktemp -d /tmp/humanish-chrome-profile.XXXXXX)"',
             '  mkdir -p "$profile_dir/Default"',

package/dist/substrates/e2b/desktop-executor.d.ts

@@ -1,4 +1,5 @@
 import type { CuaExecutor, CuaObservation } from "../../actors/computer-use/loop.js";
+import type { ExternalHandoff } from "../../actors/computer-use/external-handoff.js";
 /**
  * The minimal slice of the @e2b/desktop Sandbox the executor depends on: a structural subset of
  * the SDK class (checked against 2.4.0), so a Sandbox satisfies it with no adapter. Methods are typed to return `Promise<void> | void` (and the
@@ -65,6 +66,12 @@ export interface E2BDesktopExecutorOptions {
      * never persists raw URL/title/text; it only uses them in memory to decide whether to stop.
      */
     observeBrowserState?: () => Promise<Pick<CuaObservation, "url" | "title" | "text" | "scrollY">>;
+    /**
+     * Optional read of the links the browser handed to another app since the last read
+     * (desktop-handoff.ts). It runs beside the browser probe and the screenshot; a read that fails
+     * leaves its links for the next one.
+     */
+    readExternalHandoffs?: () => Promise<readonly ExternalHandoff[]>;
 }
 /** The stage of a `type` action that failed. */
 export type CuaTypePhase = "desktop-write" | "text-tempfile" | "text-command";

package/dist/substrates/e2b/desktop-executor.js

@@ -151,10 +151,13 @@ export function createE2BDesktopExecutor(desktop, options = {}) {
             // Probe browser state before the screenshot so a deterministic stopWhen match
             // and its persisted frame describe the same settled surface as closely as the
             // desktop substrate allows.
+            const handoffs = options.readExternalHandoffs?.().catch(() => []);
             const browserState = await options.observeBrowserState?.().catch(() => undefined);
             const raw = await desktop.screenshot();
             const screenshot = toBuffer(raw);
+            const externalHandoffs = (await handoffs) ?? [];
             return {
+                ...(externalHandoffs.length === 0 ? {} : { externalHandoffs }),
                 screenshot,
                 stateSignature: perceptualSignature(screenshot),
                 ...(browserState?.url === undefined ? {} : { url: browserState.url }),

package/dist/substrates/e2b/desktop-handoff.d.ts

@@ -0,0 +1,22 @@
+import { type ExternalHandoff } from "../../actors/computer-use/external-handoff.js";
+import { type Shell } from "../shell.js";
+/**
+ * One stand-in, installed in `bin`, appending to `log` (a shell word). `$0` names the command it
+ * stands in for. The local guest image ships the same script
+ * (runtime/browser-guest/control/root/opt/humanish/control/bin/xdg-open).
+ */
+export declare function externalLinkStandIn(bin: string, log: string): string;
+/**
+ * Shell lines for the browser launch script, run before the browser starts: they install the
+ * stand-ins and put them first on the search path for every command the script starts after them.
+ */
+export declare function externalLinkHandlerSetup(dir?: string): string;
+/**
+ * Returns a read of the links handed off since the previous read, oldest first and at most
+ * EXTERNAL_HANDOFF_LIMITS.perObservation at a time. Reads run one at a time, so a retried
+ * observation cannot return a link twice. A line still being written is left for the next read.
+ */
+export declare function externalHandoffReader(shell: Pick<Shell, "run">, options: {
+    requestTimeoutMs: number;
+    dir?: string;
+}): () => Promise<ExternalHandoff[]>;

package/dist/substrates/e2b/desktop-handoff.js

@@ -0,0 +1,86 @@
+// Links the participant's browser hands to another app (mailto:, tel:, sms:) on a hosted desktop.
+//
+// Chrome on Linux opens such a link by running `xdg-email` (mailto) or `xdg-open` (the rest) by
+// name, unless an XDG desktop portal answers on the session bus; the stock desktop runs none.
+// The stock desktop has no mail, phone or messaging app, so `xdg-open` ended in XFCE's "Choose
+// Preferred Application" dialog, which participants reported as a fault of the app under test.
+// The browser launch puts stand-ins for both commands first on the browser's search path. A stand-in
+// appends the link to a log and exits; a web or file link goes on to the desktop's own command.
+// The executor reads the log on each observation, and the participant loop records each link
+// and tells the participant what happened. Chrome's own "Open xdg-open?" prompt for tel: and
+// the other non-mailto schemes is answered by the profile preference in
+// src/evidence/browser-hygiene.ts; Chrome never prompts for mailto.
+import { EXTERNAL_HANDOFF_LIMITS, externalHandoffOf, } from "../../actors/computer-use/external-handoff.js";
+import { shellQuote } from "../shell.js";
+/** Where the stand-ins and their log live on the desktop. */
+const EXTERNAL_LINK_DIR = "/tmp/humanish-external-links";
+const LINK_LENGTH = 4096;
+/**
+ * One stand-in, installed in `bin`, appending to `log` (a shell word). `$0` names the command it
+ * stands in for. The local guest image ships the same script
+ * (runtime/browser-guest/control/root/opt/humanish/control/bin/xdg-open).
+ */
+export function externalLinkStandIn(bin, log) {
+    return [
+        "#!/bin/sh",
+        "# Installed by humanish for a study participant's browser: this desktop has no app for this",
+        "# link, so the link is written down for the study instead of opening a chooser dialog.",
+        `bin=${shellQuote(bin)}`,
+        "url=",
+        'for arg in "$@"; do case "$arg" in -*) ;; *) url=$arg; break ;; esac; done',
+        'case "$url" in',
+        "  [Hh][Tt][Tt][Pp]:*|[Hh][Tt][Tt][Pp][Ss]:*|[Ff][Ii][Ll][Ee]:*) ;;",
+        "  [A-Za-z]*:*)",
+        `    printf '%s\\n' "$(printf '%s' "$url" | tr -d '\\r\\n' | cut -c 1-${LINK_LENGTH})" >> ${log}`,
+        "    exit 0 ;;",
+        "esac",
+        // Anything else goes to the desktop's own command, found on the search path without this
+        // directory.
+        "set -f",
+        "real=",
+        "IFS=:",
+        'for entry in $PATH; do [ "$entry" = "$bin" ] || real=${real:+$real:}$entry; done',
+        'PATH=$real exec "${0##*/}" "$@"',
+        "",
+    ].join("\n");
+}
+/**
+ * Shell lines for the browser launch script, run before the browser starts: they install the
+ * stand-ins and put them first on the search path for every command the script starts after them.
+ */
+export function externalLinkHandlerSetup(dir = EXTERNAL_LINK_DIR) {
+    const bin = `${dir}/bin`;
+    return [
+        `mkdir -p ${shellQuote(bin)}`,
+        `touch ${shellQuote(`${dir}/links.log`)}`,
+        `printf '%s' ${shellQuote(externalLinkStandIn(bin, shellQuote(`${dir}/links.log`)))} > ${shellQuote(`${bin}/xdg-open`)}`,
+        `cp ${shellQuote(`${bin}/xdg-open`)} ${shellQuote(`${bin}/xdg-email`)}`,
+        `chmod 755 ${shellQuote(`${bin}/xdg-open`)} ${shellQuote(`${bin}/xdg-email`)}`,
+        `export PATH=${shellQuote(bin)}:"$PATH"`,
+    ].join("\n");
+}
+/**
+ * Returns a read of the links handed off since the previous read, oldest first and at most
+ * EXTERNAL_HANDOFF_LIMITS.perObservation at a time. Reads run one at a time, so a retried
+ * observation cannot return a link twice. A line still being written is left for the next read.
+ */
+export function externalHandoffReader(shell, options) {
+    const log = `${options.dir ?? EXTERNAL_LINK_DIR}/links.log`;
+    let consumed = 0;
+    let previous = Promise.resolve();
+    const read = async () => {
+        const result = await shell.run(`tail -n +${consumed + 1} ${shellQuote(log)} 2>/dev/null | head -n ${EXTERNAL_HANDOFF_LIMITS.perObservation}`, { requestTimeoutMs: options.requestTimeoutMs, timeoutMs: 10_000 });
+        const lines = result.stdout.split("\n");
+        lines.pop();
+        consumed += lines.length;
+        return lines.flatMap((line) => {
+            const handoff = externalHandoffOf(line);
+            return handoff === undefined ? [] : [handoff];
+        });
+    };
+    return () => {
+        const next = previous.then(read, read);
+        previous = next.catch(() => undefined);
+        return next;
+    };
+}

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

@@ -1,18 +1,18 @@
 /** Updated with the verified, public runtime artifact before release. */
 const LOCAL_RUNTIME_RELEASE = {
-    url: "https://github.com/danielgwilson/humanish/releases/download/runtime-2026.10.21.1/runtime-linux-amd64.tar.gz",
-    sha256: "1de53db000f661e91ff6ea9a2eb8198b08b850621cf63d8ce7c1b046f5035faf",
-    bytes: 597029770,
-    image: "sha256:c805c310b7b086276efa74ea5735e8b559457c7edba85c5c9e3ac7934e8760f2",
+    url: "https://github.com/danielgwilson/humanish/releases/download/runtime-2026.10.21.3/runtime-linux-amd64.tar.gz",
+    sha256: "6fc19792e9b8f414165a73470526cc414c98d0ad368210c5e95daf29469b8dbd",
+    bytes: 597049520,
+    image: "sha256:4672388737bd7d136910fca6f8b6d99e09fbe96c13e1b100491c05444e7d267a",
 };
 /** Architecture-specific artifacts; each retains matching sources and notices. */
 export const LOCAL_RUNTIME_RELEASES = {
     amd64: LOCAL_RUNTIME_RELEASE,
     arm64: {
-        url: "https://github.com/danielgwilson/humanish/releases/download/runtime-2026.10.21.2/runtime-linux-arm64.tar.gz",
-        sha256: "ea7a42e12eae3b4d9140fff41e4e3512930202f9ccbb688497b146634d1cef10",
-        bytes: 583555960,
-        image: "sha256:e21c33b4745afdb3bac6a69c76606814348032ee661228c9bfdd9c7d06591a28",
+        url: "https://github.com/danielgwilson/humanish/releases/download/runtime-2026.10.21.4/runtime-linux-arm64.tar.gz",
+        sha256: "d590de49a86eabe1cd09d7556aa75b2ebd62bc2c88fe37122e2af315c478c901",
+        bytes: 583551803,
+        image: "sha256:4606122520504f7f587f52b872165e6ab900be0ba3eca933b2f6dd3b9dcde723",
     },
 };
 /** Media assets are separate so ordinary browser studies keep the smaller download. */