humanish 0.140.0 → 0.141.0

package/dist/analysis/service.js

@@ -1,7 +1,7 @@
 import { defaultCodexCliVersion, describeCodexCliAdmission, } from "../actors/codex/codex-admission.js";
 import { validCodexAnalysisConfig } from "./codex-config.js";
 import { randomUUID } from "node:crypto";
-import { lstat, mkdir, realpath, rmdir } from "node:fs/promises";
+import { realpath } from "node:fs/promises";
 import path from "node:path";
 import { renderObserver } from "../observer/render.js";
 import { containsSensitive } from "../evidence/redaction.js";
@@ -11,6 +11,8 @@ import { verifyRunPrepared } from "../verify/verify.js";
 import { loadRunBundlePrepared, resolveRunPath } from "../run/locate.js";
 import { physicalCwdOf, runIdOf, resolvePhysicalCwd, validatePreparedRunRootIdentity, } from "../run/paths.js";
 import { isRunStatusRecord, RUN_STATUS_FILE } from "../run/status.js";
+import { assertRecordingEnded } from "./recording-ended.js";
+import { withAnalysisLock } from "./analysis-lock.js";
 import { captureEvidence, EVIDENCE_LIMITS } from "./evidence.js";
 import { AnalysisSourceRefusedError, runFileTooLarge, throwAsAnalysisRefusal } from "./source.js";
 import { pathMissing, readBoundedFile, readBoundedFileResult } from "../run/evidence-files.js";
@@ -46,12 +48,12 @@ export async function resolveAnalysisRun(cwd, run, expectedRun) {
 const messages = {
     ANALYSIS_RUN_NOT_FOUND: "The selected run is unavailable or its storage is unsafe.",
     ANALYSIS_VERIFY_FAILED: "The run must pass verification before analysis.",
-    ANALYSIS_RUN_ACTIVE: "Analysis requires a completed recording. Wait for the study to finish.",
+    ANALYSIS_RUN_ACTIVE: "This run's status.json is missing, unreadable or names another run, so humanish cannot tell whether its recording has ended. `humanish verify` checks the run's files.",
     ANALYSIS_NO_PARTICIPANTS: "This run contains no participant evidence to analyze.",
     ANALYSIS_REQUIRES_LIVE_RUN: "A dry run has no participant behavior to analyze. Select a completed live run.",
     ANALYSIS_SOURCE_UNAVAILABLE: "The source recording is missing or unsafe.",
     ANALYSIS_SOURCE_CHANGED: "The source recording changed during analysis. The result cannot be published against different evidence.",
-    ANALYSIS_BUSY: "Another analysis holds this run's .analysis-lock directory. If it was interrupted, confirm it has stopped before removing that empty directory.",
+    ANALYSIS_BUSY: "Another analysis holds this run's .analysis-lock directory, and its process is still running or humanish cannot check it (another host, or a lock written by humanish 0.139.1 or earlier). Wait for it to finish; if no humanish process is running for this run, remove that directory.",
     ANALYSIS_HISTORY_UNAVAILABLE: "Analysis history is unavailable or full. No request was sent. Inspect this run's analysis and analysis-attempts storage before retrying.",
     ANALYSIS_CONFIG_INVALID: "OpenAI analysis needs a supported model, positive USD admission limit and 256–32768 output tokens. Codex account analysis uses its qualified model and null dollar/output-token caps. Both require timeout 1–600000 ms.",
     ANALYSIS_QUESTION_UNSAFE: "The reviewer question matched a sensitive-text pattern. Remove sensitive details before retrying.",
@@ -109,43 +111,7 @@ export async function refreshObserver(cwd, runId, prepared) {
         return false;
     }
 }
-/** One analysis or correction writer per run. Never steal a lock based on an untrusted PID. */
-export async function withAnalysisLock(prepared, action) {
-    await validatePreparedRunRootIdentity(prepared);
-    const target = path.join(prepared.physicalRunRoot, ".analysis-lock");
-    try {
-        await mkdir(target, { mode: 0o700 });
-    }
-    catch (error) {
-        if (error.code === "EEXIST")
-            throw new Error("ANALYSIS_BUSY");
-        throw new Error("ANALYSIS_UNAVAILABLE");
-    }
-    const identity = await lstat(target, { bigint: true });
-    try {
-        await validatePreparedRunRootIdentity(prepared);
-        if (!identity.isDirectory() || identity.isSymbolicLink())
-            throw new Error("ANALYSIS_UNAVAILABLE");
-        return await action();
-    }
-    finally {
-        // Only remove our empty, unchanged directory. No recursive deletion and no replacement authority.
-        try {
-            await validatePreparedRunRootIdentity(prepared);
-            const current = await lstat(target, { bigint: true });
-            if (current.isDirectory() &&
-                !current.isSymbolicLink() &&
-                current.dev === identity.dev &&
-                current.ino === identity.ino &&
-                current.birthtimeNs === identity.birthtimeNs)
-                await rmdir(target);
-        }
-        catch {
-            /* Leave ambiguous storage in place for explicit operator inspection. */
-        }
-    }
-}
-/** The completion gate: the run verifies, is live and finished, and has participants. */
+/** The completion gate: the run verifies, is live, its recording ended, and it has participants. */
 export async function readCompletedAnalysisSource(cwd, prepared) {
     const read = await readBoundedFileResult(prepared, RUN_BUNDLE_FILE, EVIDENCE_LIMITS.sourceBytes);
     if (read.state === "limit")
@@ -170,18 +136,19 @@ export async function readCompletedAnalysisSource(cwd, prepared) {
         if (!missing)
             throw new Error("ANALYSIS_RUN_ACTIVE");
     }
+    let status;
     if (statusBytes) {
-        const status = JSON.parse(statusBytes.toString("utf8"));
-        // An old heartbeat is unknown, not proof that a process stopped writing evidence.
-        if (!isRunStatusRecord(status) ||
-            status.runId !== loaded.bundle.runId ||
-            status.state !== "finished") {
+        const record = JSON.parse(statusBytes.toString("utf8"));
+        if (!isRunStatusRecord(record) || record.runId !== loaded.bundle.runId)
             throw new Error("ANALYSIS_RUN_ACTIVE");
-        }
-    }
-    if (loaded.bundle.streams.some((stream) => !TERMINAL_SIMULATION_STATUSES.has(stream.status) || stream.liveActor !== undefined)) {
-        throw new Error("ANALYSIS_RUN_ACTIVE");
+        status = record;
     }
+    assertRecordingEnded({
+        runId: loaded.bundle.runId,
+        status,
+        runningStreams: loaded.bundle.streams.filter((stream) => !TERMINAL_SIMULATION_STATUSES.has(stream.status) || stream.liveActor !== undefined).length,
+        streams: loaded.bundle.streams.length,
+    });
     return bytes;
 }
 /** The refusal code for a configuration analyzeRun cannot run, before any run file is read. */
@@ -384,7 +351,13 @@ export async function analyzeRun(cwdInput, run, options, deps = {}) {
         if (deps.expectedRun !== undefined)
             cwd = physicalCwdOf(prepared);
         const execute = () => executeAnalysis({ cwd, run, prepared, config, options, deps, dryRun });
-        return dryRun ? await execute() : await withAnalysisLock(prepared, execute);
+        if (dryRun)
+            return await execute();
+        const tookOver = [];
+        const result = await withAnalysisLock(prepared, execute, (warning) => tookOver.push(warning));
+        return tookOver.length === 0
+            ? result
+            : { ...result, warnings: [...tookOver, ...result.warnings] };
     }
     catch (error) {
         if (error instanceof AnalysisSourceRefusedError)

package/dist/analysis/source.d.ts

@@ -7,7 +7,7 @@ import type { RunStream, StoredRunStream } from "../run/streams.js";
  */
 export declare class AnalysisSourceRefusedError extends Error {
     readonly reason: string;
-    constructor(code: "ANALYSIS_SOURCE_TOO_LARGE" | "ANALYSIS_SOURCE_INVALID", reason: string);
+    constructor(code: "ANALYSIS_SOURCE_TOO_LARGE" | "ANALYSIS_SOURCE_INVALID" | "ANALYSIS_RUN_ACTIVE" | "ANALYSIS_RUN_INCOMPLETE" | "ANALYSIS_RUN_UNCONFIRMED", reason: string);
 }
 /** The refusal of a run.json of `size` bytes, more than the `max` analysis reads of it. */
 export declare function runFileTooLarge(size: number | bigint, max: number): AnalysisSourceRefusedError;

package/dist/browser-control/protocol.d.ts

@@ -287,6 +287,10 @@ declare const observationSchema: z.ZodObject<{
         text: z.ZodString;
         durationMs: z.ZodNumber;
     }, z.core.$strict>>>;
+    externalHandoffs: z.ZodOptional<z.ZodArray<z.ZodObject<{
+        scheme: z.ZodString;
+        recipients: z.ZodOptional<z.ZodArray<z.ZodString>>;
+    }, z.core.$strict>>>;
 }, z.core.$strict>;
 type WireObservation = z.infer<typeof observationSchema>;
 declare const requestSchema: z.ZodDiscriminatedUnion<[z.ZodObject<{
@@ -503,6 +507,10 @@ declare const replySchema: z.ZodDiscriminatedUnion<[z.ZodObject<{
             text: z.ZodString;
             durationMs: z.ZodNumber;
         }, z.core.$strict>>>;
+        externalHandoffs: z.ZodOptional<z.ZodArray<z.ZodObject<{
+            scheme: z.ZodString;
+            recipients: z.ZodOptional<z.ZodArray<z.ZodString>>;
+        }, z.core.$strict>>>;
     }, z.core.$strict>>;
     recording: z.ZodOptional<z.ZodObject<{
         mimeType: z.ZodLiteral<"video/mp4">;

package/dist/browser-control/protocol.js

@@ -1,6 +1,7 @@
 import { PNG } from "pngjs";
 import { z } from "zod";
 import { CUA_SPEECH_LIMITS } from "../actors/computer-use/speech.js";
+import { EXTERNAL_HANDOFF_LIMITS } from "../actors/computer-use/external-handoff.js";
 import { ComputerUseExecutorError, CUA_REJECTION_REASONS, isComputerUseExecutorError, } from "../actors/computer-use/executor-error.js";
 import { CUA_DIAGNOSTIC_CATEGORIES, CUA_DIAGNOSTIC_STEPS, } from "../actors/computer-use/executor-diagnostic.js";
 import { desktopRecordingMetadataSchema } from "../evidence/desktop-recording-types.js";
@@ -152,6 +153,17 @@ const heardSpeechListSchema = z
     .min(1)
     .max(BROWSER_CONTROL_LIMITS.heardSpeech)
     .refine((rows) => new Set(rows.map((row) => row.id)).size === rows.length);
+// The guest sends a handoff as externalHandoffOf made it: a scheme and a mailto link's recipients.
+const externalHandoffListSchema = z
+    .array(z.strictObject({
+    scheme: z.string().regex(/^[a-z][a-z0-9+.-]{0,31}$/),
+    recipients: z
+        .array(z.string().min(3).max(EXTERNAL_HANDOFF_LIMITS.addressLength))
+        .max(EXTERNAL_HANDOFF_LIMITS.recipients)
+        .optional(),
+}))
+    .min(1)
+    .max(EXTERNAL_HANDOFF_LIMITS.perObservation);
 const observationSchema = z.strictObject({
     png: z
         .string()
@@ -165,6 +177,7 @@ const observationSchema = z.strictObject({
     text: text.optional(),
     scrollY: coordinate.optional(),
     heardSpeech: heardSpeechListSchema.optional(),
+    externalHandoffs: externalHandoffListSchema.optional(),
 });
 const common = {
     version: z.literal(BROWSER_CONTROL_VERSION),
@@ -344,6 +357,9 @@ export function encodeBrowserControlObservation(observation) {
         ...(observation.text !== undefined ? { text: observation.text } : {}),
         ...(observation.scrollY !== undefined ? { scrollY: observation.scrollY } : {}),
         ...(observation.heardSpeech !== undefined ? { heardSpeech: observation.heardSpeech } : {}),
+        ...(observation.externalHandoffs !== undefined
+            ? { externalHandoffs: observation.externalHandoffs }
+            : {}),
     });
     if (!parsed.success)
         throw new ComputerUseExecutorError("invalid_response", "outcome_uncertain");
@@ -366,6 +382,11 @@ export function decodeBrowserControlObservation(value) {
         ...(state.text !== undefined ? { text: state.text } : {}),
         ...(state.scrollY !== undefined ? { scrollY: state.scrollY } : {}),
         ...(state.heardSpeech !== undefined ? { heardSpeech: state.heardSpeech } : {}),
+        ...(state.externalHandoffs !== undefined
+            ? {
+                externalHandoffs: state.externalHandoffs.map(({ scheme, recipients }) => recipients === undefined ? { scheme } : { scheme, recipients }),
+            }
+            : {}),
     };
 }
 export function safeBrowserControlFailure(error, dispatched) {

package/dist/cli/commands/analysis-signals.d.ts

@@ -1,8 +1,14 @@
 import type { RunStudyOptions } from "../../run-study.js";
+import { type HostClock } from "../../run/host-suspension.js";
 import type { CliIo } from "../io.js";
 /**
- * Post-run analysis cancellation for the CLI: while analysis runs, SIGINT, SIGTERM and SIGHUP abort
- * it. The listeners exist only during analysis; before it, the run's own handlers
- * (run-signals.ts) hold the signals and hand them over here.
+ * The CLI's run events. When the run starts, one stderr line names it and the command that
+ * follows it. While analysis runs, SIGINT, SIGTERM and SIGHUP abort it; the listeners exist only
+ * during analysis, since before it the run's own handlers (run-signals.ts) hold the signals and
+ * hand them over here. A human also gets a line when analysis starts and one with its elapsed
+ * time every 20 s; `--json` gets only the first line, on stderr, so stdout stays one result.
  */
-export declare function cliAnalysisOptions(io: Pick<CliIo, "writeErr">): Pick<RunStudyOptions, "onEvent" | "analysisSignal">;
+export declare function cliRunEventOptions(io: Pick<CliIo, "writeErr">, options?: {
+    json?: boolean;
+    clock?: HostClock;
+}): Pick<RunStudyOptions, "onEvent" | "analysisSignal">;

package/dist/cli/commands/analysis-signals.js

@@ -1,25 +1,47 @@
+import { ANALYSIS_USUALLY_TAKES } from "../../analysis/analysis-limits.js";
+import { systemHostClock } from "../../run/host-suspension.js";
+import { formatDuration } from "../../run/projection.js";
+import { cli } from "../invocation.js";
 import { handOverRunSignals } from "./run-signals.js";
+/** How often a human sees how long analysis has run: often enough to look alive, rarely enough
+ *  to read as one line per glance. */
+const ANALYSIS_PROGRESS_MS = 20_000;
 /**
- * Post-run analysis cancellation for the CLI: while analysis runs, SIGINT, SIGTERM and SIGHUP abort
- * it. The listeners exist only during analysis; before it, the run's own handlers
- * (run-signals.ts) hold the signals and hand them over here.
+ * The CLI's run events. When the run starts, one stderr line names it and the command that
+ * follows it. While analysis runs, SIGINT, SIGTERM and SIGHUP abort it; the listeners exist only
+ * during analysis, since before it the run's own handlers (run-signals.ts) hold the signals and
+ * hand them over here. A human also gets a line when analysis starts and one with its elapsed
+ * time every 20 s; `--json` gets only the first line, on stderr, so stdout stays one result.
  */
-export function cliAnalysisOptions(io) {
+export function cliRunEventOptions(io, options = {}) {
+    const clock = options.clock ?? systemHostClock;
     const controller = new AbortController();
     const cancel = () => {
         controller.abort();
     };
     const signals = ["SIGINT", "SIGTERM", "SIGHUP"];
+    let stopProgress;
     return {
         analysisSignal: controller.signal,
         onEvent: (event) => {
-            if (event.type === "analysis-started") {
-                io.writeErr("Participants finished; preparing analysis…\n");
+            if (event.type === "run-started") {
+                io.writeErr(`Run ${event.runId} started. Follow it with ${cli(`observe --run ${event.runId}`)}; ${cli("runs")} lists its state.\n`);
+            }
+            else if (event.type === "analysis-started") {
+                io.writeErr(`Participants finished. Writing findings; this usually takes ${ANALYSIS_USUALLY_TAKES}.\n`);
+                if (options.json !== true) {
+                    const startedMs = clock.now();
+                    stopProgress = clock.every(ANALYSIS_PROGRESS_MS, () => {
+                        io.writeErr(`Still writing findings: ${formatDuration(clock.now() - startedMs)} elapsed.\n`);
+                    });
+                }
                 handOverRunSignals();
                 for (const signal of signals)
                     process.on(signal, cancel);
             }
             else if (event.type === "analysis-finished") {
+                stopProgress?.();
+                stopProgress = undefined;
                 for (const signal of signals)
                     process.off(signal, cancel);
             }

package/dist/cli/commands/runs.js

@@ -6,7 +6,7 @@ import { DEFAULT_EXPORT_MAX_BYTES, exportRun, formatExportHuman } from "../../fe
 import { listRuns, readReview } from "../../run/stored-runs.js";
 import { verifyRun } from "../../verify/verify.js";
 import { reclaimPreflightSandboxes, reclaimRunSandboxes, } from "../../run/reclaim.js";
-import { runDisplay } from "../../run/display.js";
+import { analysisPhaseLabel, runDisplay } from "../../run/display.js";
 import { addRunOptions, handleRun } from "./run-command.js";
 import { applyEnvFileOption, CWD_OPTION_DESCRIPTION, DOTENV_OPTION_DESCRIPTION, dotenvPathOf, envFileAliasOption, JSON_OPTION_DESCRIPTION, parsePositiveInteger, RUN_OPTION_DESCRIPTION, writeResult, humanError, } from "../io.js";
 import { plural } from "../../run/text.js";
@@ -251,6 +251,8 @@ function formatReclaimHuman(result, cwd, preflight) {
     for (const outcome of result.outcomes) {
         lines.push(`  sandbox ${outcome.sandboxIdDigest} (${outcome.laneId}, from ${outcome.source}): ${outcome.state}${outcome.detail ? `: ${outcome.detail}` : ""}`);
     }
+    if (result.markedInterrupted === true)
+        lines.push("Its status.json had stopped updating while it still said running, so the run is now recorded as interrupted.");
     for (const warning of result.warnings)
         lines.push(`  warning: ${warning}`);
     if (result.error === undefined && result.state !== "clean")
@@ -378,6 +380,10 @@ function formatRunsHuman(result) {
     }
     return ([
         `latest: ${result.latest ?? "none"}`,
-        ...result.runs.map((run) => `- ${run.runId} ${run.mode ?? "unknown"} ${run.display?.label ?? "unreadable"} ${run.createdAt ?? "unknown"} ${run.path}`),
+        ...result.runs.map((run) => {
+            const analysis = analysisPhaseLabel(run.analysis);
+            const label = `${run.display?.label ?? "unreadable"}${analysis === undefined ? "" : `, ${analysis}`}`;
+            return `- ${run.runId} ${run.mode ?? "unknown"} ${label} ${run.createdAt ?? "unknown"} ${run.path}`;
+        }),
     ].join("\n") + "\n");
 }

package/dist/cli/commands/study-route-computer-use.js

@@ -5,7 +5,7 @@ import { resolveStudyDryRun } from "../../study/plan.js";
 import { serveObserver } from "../../observer/render.js";
 import { startExposedObserver, validateExposure } from "../../observer/exposure.js";
 import { ServeTunnelError } from "../../observer/tunnel.js";
-import { cliAnalysisOptions } from "./analysis-signals.js";
+import { cliRunEventOptions } from "./analysis-signals.js";
 import { onRunShutdown } from "./run-signals.js";
 import { parseStudyCount, parseParticipantIds, parseObserverPort, wantsJson, writeResult, } from "../io.js";
 import { exposureRequestFromOptions, followDecision, followObserver, planObserver, showObserver, staticObserverOpen, withObserverServer, } from "../observer-follow.js";
@@ -127,7 +127,7 @@ function prepareCuaWatch(args, settings) {
 function cuaRunOptions(args, settings, prepared, live) {
     const { finishedPlan } = prepared;
     return {
-        ...cliAnalysisOptions(args.io),
+        ...cliRunEventOptions(args.io, { json: wantsJson(args.command) }),
         cwd: args.options.cwd,
         // A followed watch opens the served Observer (or prints the phone target under --expose), so
         // its static render never opens. A non-follow watch opens what its plan says, once. Run mode

package/dist/cli/commands/study-route-scripted.js

@@ -1,6 +1,6 @@
 import { automaticAnalysisSucceeded } from "../../analysis/automatic-completion.js";
 import { Command } from "commander";
-import { cliAnalysisOptions } from "./analysis-signals.js";
+import { cliRunEventOptions } from "./analysis-signals.js";
 import { wantsJson } from "../io.js";
 import { writeRunResult } from "../run-findings.js";
 import { showObserver } from "../observer-follow.js";
@@ -23,7 +23,7 @@ export function scriptedRouteRun(args) {
         return undefined;
     return {
         options: {
-            ...cliAnalysisOptions(args.io),
+            ...cliRunEventOptions(args.io, { json: wantsJson(args.command) }),
             cwd: args.options.cwd,
             open: observerOpen(args.mode, finishedPlan, shouldOpen),
             ...(args.options.dryRun === undefined ? {} : { dryRun: args.options.dryRun }),

package/dist/cli/commands/study-route-shared-world.js

@@ -3,7 +3,7 @@ import { Command } from "commander";
 import { resolveStudyDryRun } from "../../study/plan.js";
 import { serveObserver } from "../../observer/render.js";
 import { redactText } from "../../evidence/redaction.js";
-import { cliAnalysisOptions } from "./analysis-signals.js";
+import { cliRunEventOptions } from "./analysis-signals.js";
 import { parseObserverPort, wantsJson, writeResult, } from "../io.js";
 import { followDecision, followObserver, showObserver, staticObserverOpen, withObserverServer, } from "../observer-follow.js";
 import { writeRunResult } from "../run-findings.js";
@@ -65,7 +65,7 @@ export function sharedWorldRouteRun(args) {
     let observerFailure;
     return {
         options: {
-            ...cliAnalysisOptions(args.io),
+            ...cliRunEventOptions(args.io, { json: wantsJson(args.command) }),
             cwd: args.options.cwd,
             open: wantsFollow
                 ? false

package/dist/cli/commands/study-route-terminal.js

@@ -1,6 +1,6 @@
 import { automaticAnalysisSucceeded } from "../../analysis/automatic-completion.js";
 import { Command } from "commander";
-import { cliAnalysisOptions } from "./analysis-signals.js";
+import { cliRunEventOptions } from "./analysis-signals.js";
 import { wantsJson } from "../io.js";
 import { writeRunResult } from "../run-findings.js";
 import { showObserver } from "../observer-follow.js";
@@ -23,7 +23,7 @@ export function terminalRouteRun(args) {
         return undefined;
     return {
         options: {
-            ...cliAnalysisOptions(args.io),
+            ...cliRunEventOptions(args.io, { json: wantsJson(args.command) }),
             cwd: args.options.cwd,
             open: observerOpen(args.mode, finishedPlan, shouldOpen),
             ...(args.options.dryRun === undefined ? {} : { dryRun: args.options.dryRun }),

package/dist/cli/findings.d.ts

@@ -1,4 +1,5 @@
 import type { AnalysisArtifact, LoadedAnalysis } from "../analysis/types.js";
+import { type RunAnalysisPhase } from "../run/status.js";
 import { type RunStudyProvenance } from "../run/study-provenance.js";
 export declare const ANALYSIS_FINDINGS_SCHEMA = "humanish.analysis-findings.v1";
 type Finding = NonNullable<AnalysisArtifact["result"]>["findings"][number];
@@ -121,6 +122,28 @@ interface FindingsSource {
      * skipped for a missing OpenAI key, whose next step it picks.
      */
     codexSignedIn?: boolean;
+    /**
+     * Where the run is before its findings, from status.json: its participants still running, or
+     * the automatic analysis its own process started. Undefined once neither applies.
+     */
+    progress?: {
+        stage: "participants";
+    }
+    /** The run ended while a participant stream was still running: nothing complete to analyze. */
+     | {
+        stage: "cut-off";
+        running: number;
+        streams: number;
+    } | {
+        stage: "analysis";
+        phase: RunAnalysisPhase;
+        /** status.json's last heartbeat. */
+        updatedAt: string;
+        /** The analyst the run's study gets, read only for an analysis whose process stopped. */
+        provider?: string;
+    };
+    /** When the view was built, for how long an analysis has run. */
+    nowMs?: number;
 }
 /** A study `run` can start live after a dry run. */
 interface LiveStudy {

package/dist/cli/findings.js

@@ -5,11 +5,15 @@
 // starts an analysis.
 import path from "node:path";
 import { costRefusal } from "../analysis/admission.js";
-import { DEFAULT_ANALYSIS_MAX_COST_USD } from "../analysis/automatic-config.js";
+import { DEFAULT_ANALYSIS_MAX_COST_USD, resolveAutomaticAnalysis, } from "../analysis/automatic-config.js";
+import { ANALYSIS_USUALLY_TAKES } from "../analysis/analysis-limits.js";
 import { bySeverity } from "../analysis/finding-lead.js";
 import { loadAnalysis } from "../analysis/load.js";
 import { projectShareCheckedAnalysis } from "../analysis/sharing.js";
-import { loadRunBundlePrepared, resolveRunPath } from "../run/locate.js";
+import { loadRunBundlePrepared, readRunJsonIfExists, resolveRunPath, runJsonValue, } from "../run/locate.js";
+import { classifyRunStatus, isRunStatusRecord, RUN_STATUS_FILE, runAnalysisPhase, } from "../run/status.js";
+import { TERMINAL_SIMULATION_STATUSES } from "../run/streams.js";
+import { formatDuration } from "../run/projection.js";
 import { resolvePhysicalCwd, runIdOf } from "../run/paths.js";
 import { studyProvenanceOf } from "../run/study-provenance.js";
 import { resolveStudyManifest } from "../study/discover.js";
@@ -164,6 +168,57 @@ function missingKeyFindings(source, reason) {
     const file = source.study?.path === undefined ? "the study file" : source.study.path;
     return withoutFindings(source, "skipped", reason, `${opening} Codex is signed in on this machine, so its ChatGPT account can analyze the run instead, sending the evidence to OpenAI under that account. The next command does it once; review.analysis.provider: codex in ${file} makes it this study's analyst.`, analyzeCommand(source, "codex"));
 }
+/**
+ * The view of a run whose findings are not written yet: participants still running, an analysis
+ * running, or an analysis whose process stopped before it finished. Undefined otherwise.
+ */
+function pendingFindings(source, job) {
+    const again = cli(`review --run ${source.runId}${source.cwdFlag}`);
+    const progress = source.progress;
+    if (progress?.stage === "participants" && job === undefined)
+        return withoutFindings(source, "running", null, source.analysisOffIn === undefined
+            ? "Participants are still running in this run, so no analysis has started. Automatic analysis starts when they finish, and the findings follow it."
+            : "Participants are still running in this run. Analysis is turned off in its study, so none starts when they finish.", again);
+    if (progress?.stage === "cut-off" && job === undefined)
+        return withoutFindings(source, "skipped", "ANALYSIS_RUN_INCOMPLETE", `This run ended while ${progress.running} of ${progress.streams} participant streams were still running, so its recording is incomplete and no analysis ran. Run the study again with the next command.`, cli(`run ${source.study?.id ?? "<study>"}${source.cwdFlag}`));
+    const phase = progress?.stage === "analysis" ? progress.phase : undefined;
+    const jobPending = job?.state === "queued" || job?.state === "running";
+    if (jobPending || (job === undefined && phase?.state === "running")) {
+        const since = phase === undefined
+            ? ""
+            : ` It started at ${phase.startedAt}, ${formatDuration(Math.max(0, (source.nowMs ?? Date.now()) - Date.parse(phase.startedAt)))} ago.`;
+        return withoutFindings(source, "running", null, `The automatic analysis is running.${since} Findings usually take ${ANALYSIS_USUALLY_TAKES}; check again then.`, again);
+    }
+    const stopped = (job?.state === "unknown" && job.reason === "AUTOMATIC_ANALYSIS_STOPPED") ||
+        (job === undefined && phase?.state === "stopped");
+    if (!stopped)
+        return undefined;
+    const at = job?.updatedAt ?? (progress?.stage === "analysis" ? progress.updatedAt : undefined);
+    return withoutFindings(source, "failed", "AUTOMATIC_ANALYSIS_STOPPED", `The automatic analysis stopped before it wrote findings: the process running it stopped updating its record${at === undefined ? "" : ` at ${at}`}, most likely because it ended. Analyze the run again with the next command.`, analyzeCommand(source, progress?.stage === "analysis" ? progress.provider : undefined));
+}
+/**
+ * A run that ended, by a signal, a process that left without publishing, or a heartbeat that
+ * stopped, while some participant stream was still running. Undefined for any other run.
+ */
+function cutOff(bundle, record, nowMs) {
+    if (bundle === undefined || bundle.outcome?.state === "finished")
+        return undefined;
+    if (bundle.outcome === undefined &&
+        (record === null || classifyRunStatus(record, nowMs) !== "interrupted"))
+        return undefined;
+    const running = bundle.streams.filter((stream) => !TERMINAL_SIMULATION_STATUSES.has(stream.status) || stream.liveActor !== undefined).length;
+    return running === 0 ? undefined : { stage: "cut-off", running, streams: bundle.streams.length };
+}
+/** The analyst the run's study gets, when its file still names the same study. */
+async function studyAnalyst(cwd, study) {
+    if (study?.path === undefined)
+        return undefined;
+    const resolved = await resolveStudyManifest(cwd, study.path).catch(() => null);
+    if (!resolved?.ok || resolved.config.id !== study.id)
+        return undefined;
+    const analysis = resolveAutomaticAnalysis(resolved.config.review?.analysis, resolved.config.actor);
+    return analysis.ok ? analysis.config?.provider : undefined;
+}
 /** The findings view of a run's selected analysis, or why it has none. */
 export function analysisFindings(source) {
     if (source.mode !== undefined && source.mode !== "live")
@@ -200,8 +255,9 @@ export function analysisFindings(source) {
     if (loaded.warnings.includes("ANALYSIS_SENSITIVE_TEXT_QUARANTINED"))
         return withoutFindings(source, "unavailable", "ANALYSIS_SENSITIVE_TEXT_QUARANTINED", `The analysis text matched a sensitive-text pattern, so it is not printed. ${cli(`analyze show --run ${source.runId}${source.cwdFlag} --json`)} prints the raw record.`, null);
     const job = loaded.automatic;
-    if (job?.state === "queued" || job?.state === "running")
-        return withoutFindings(source, "running", null, "The automatic analysis is still running. Check again when it finishes.", cli(`review --run ${source.runId}${source.cwdFlag}`));
+    const pending = pendingFindings(source, job);
+    if (pending !== undefined)
+        return pending;
     if (analysis && analysis.result === null)
         return withoutFindings(source, "failed", analysis.error, `Analysis attempt ${analysis.id} ${analysis.status === "cancelled" ? "was cancelled" : "failed"}${analysis.error ? ` (${analysis.error})` : ""} and left no findings.`, analyzeCommand(source, analysis.provider));
     if (job?.state === "failed" || job?.state === "cancelled") {
@@ -278,6 +334,24 @@ export async function readRunAnalysis(cwd, run, analysisId, deps = {}) {
     const analysisOffIn = mode === "live" ? await studyAnalysisOff(physical, study) : undefined;
     const liveStudy = mode !== undefined && mode !== "live" ? await liveStudyAfterDryRun(physical, study) : undefined;
     const loaded = await loadAnalysis(prepared, analysisId);
+    const nowMs = Date.now();
+    const status = runJsonValue(await readRunJsonIfExists(prepared, RUN_STATUS_FILE));
+    const record = isRunStatusRecord(status) && status.runId === runIdOf(prepared) ? status : null;
+    const phase = record === null ? undefined : runAnalysisPhase(record, nowMs);
+    const stopped = phase?.state === "stopped" || loaded.automatic?.reason === "AUTOMATIC_ANALYSIS_STOPPED";
+    const provider = stopped ? await studyAnalyst(physical, study) : undefined;
+    const progress = phase !== undefined && record !== null
+        ? {
+            stage: "analysis",
+            phase,
+            updatedAt: record.updatedAt,
+            ...(provider === undefined ? {} : { provider }),
+        }
+        : bundle?.bundle.outcome === undefined &&
+            record !== null &&
+            classifyRunStatus(record, nowMs) === "running"
+            ? { stage: "participants" }
+            : cutOff(bundle?.bundle, record, nowMs);
     const codexSignedIn = loaded.automatic?.reason === "AUTOMATIC_ANALYSIS_KEY_MISSING"
         ? await (deps.codexSignedIn ?? codexSignedInHere)().catch(() => false)
         : undefined;
@@ -293,6 +367,8 @@ export async function readRunAnalysis(cwd, run, analysisId, deps = {}) {
             ? {}
             : { study: { id: study.id, ...(study.path === undefined ? {} : { path: study.path }) } }),
         ...(codexSignedIn === undefined ? {} : { codexSignedIn }),
+        ...(progress === undefined ? {} : { progress }),
+        nowMs,
     };
 }
 async function codexSignedInHere() {

package/dist/cli/io.js

@@ -315,6 +315,7 @@ const ANALYSIS_REASON_TEXT = {
     AUTOMATIC_ANALYSIS_CANCELLATION_UNAVAILABLE: "outcome unknown: a cancellation could not be recorded",
     AUTOMATIC_ANALYSIS_STORAGE_UNAVAILABLE: "outcome unknown: analysis storage is unavailable",
     AUTOMATIC_ANALYSIS_OUTCOME_UNKNOWN: "outcome unknown",
+    AUTOMATIC_ANALYSIS_STOPPED: "outcome unknown: the process running it stopped before it finished",
 };
 export function analysisOutcomeText(analysis) {
     if (analysis.reason === null)

package/dist/evidence/browser-hygiene.d.ts

@@ -4,4 +4,15 @@
  * place so browser-backed routes can prefer product pixels over browser UI.
  */
 export declare const CHROMIUM_EVIDENCE_HYGIENE_FLAGS: readonly ["--disable-background-networking", "--disable-component-update", "--disable-default-apps", "--disable-domain-reliability", "--disable-extensions", "--disable-sync", "--no-default-browser-check", "--no-first-run", "--password-store=basic", "--use-mock-keychain"];
-export declare function chromiumEvidenceProfilePreferencesJson(): string;
+/**
+ * The profile preference that lets a web `targetUrl`'s origin open the external app schemes
+ * without Chrome's prompt: the "always allow" choice Chrome stores per origin, which needs no root
+ * and no managed policy. Links from other origins still prompt. Undefined for any other target.
+ */
+export declare function externalAppPreferences(targetUrl: string | undefined): {
+    protocol_handler: {
+        allowed_origin_protocol_pairs: Record<string, Record<string, true>>;
+    };
+} | undefined;
+/** The profile's Preferences file, with externalAppPreferences for a web `targetUrl`. */
+export declare function chromiumEvidenceProfilePreferencesJson(targetUrl?: string): string;

package/dist/evidence/browser-hygiene.js

@@ -37,6 +37,49 @@ const CHROMIUM_EVIDENCE_PROFILE_PREFERENCES = {
         password_manager_enabled: false,
     },
 };
-export function chromiumEvidenceProfilePreferencesJson() {
-    return JSON.stringify(CHROMIUM_EVIDENCE_PROFILE_PREFERENCES);
+/**
+ * Schemes whose links Chrome hands to another app after asking "Open xdg-open?". The desktop's
+ * stand-ins answer them (src/substrates/e2b/desktop-handoff.ts), so the prompt is browser chrome
+ * a person on their own computer would not see for that app. Chrome never asks for mailto.
+ */
+const EXTERNAL_APP_SCHEMES = [
+    "callto",
+    "facetime",
+    "facetime-audio",
+    "geo",
+    "maps",
+    "mms",
+    "msteams",
+    "sip",
+    "skype",
+    "slack",
+    "sms",
+    "tel",
+    "webcal",
+    "whatsapp",
+    "zoommtg",
+];
+/**
+ * The profile preference that lets a web `targetUrl`'s origin open the external app schemes
+ * without Chrome's prompt: the "always allow" choice Chrome stores per origin, which needs no root
+ * and no managed policy. Links from other origins still prompt. Undefined for any other target.
+ */
+export function externalAppPreferences(targetUrl) {
+    const target = targetUrl === undefined ? null : URL.parse(targetUrl);
+    if (target === null || !/^https?:$/.test(target.protocol))
+        return undefined;
+    return {
+        protocol_handler: {
+            allowed_origin_protocol_pairs: {
+                [target.origin]: Object.fromEntries(EXTERNAL_APP_SCHEMES.map((scheme) => [scheme, true])),
+            },
+        },
+    };
+}
+/** The profile's Preferences file, with externalAppPreferences for a web `targetUrl`. */
+export function chromiumEvidenceProfilePreferencesJson(targetUrl) {
+    return JSON.stringify({
+        ...CHROMIUM_EVIDENCE_PROFILE_PREFERENCES,
+        ...externalAppPreferences(targetUrl),
+    });
 }

package/dist/feedback/export-bundle.js

@@ -47,7 +47,7 @@ function omittedReason(relative) {
         return "automatic execution intent and liveness do not transfer to a derivative";
     if (isAnalysisRecordPath(relative))
         return "analysis records bind original evidence hashes; reanalyze the derivative";
-    if (relative.startsWith(".analysis-lock/"))
+    if (relative.startsWith(".analysis-lock"))
         return "local analysis execution lock";
     return (OMITTED.get(relative) ??
         (["feedback/draft.json", "feedback/issue.md"].includes(relative)