humanish 0.105.0 → 0.106.0

package/dist/analysis/automatic.js

@@ -0,0 +1,279 @@
+import path from "node:path";
+import { resolveRunPath } from "../run/locate.js";
+import {} from "../run/bundle.js";
+import { refreshObserver, analyzeRun, readCompletedAnalysisSource, resolveAnalysisRun, } from "./service.js";
+import { preferLargerAnalysisOutput, ANALYSIS_PROMPT_VERSION } from "./execute.js";
+import { captureEvidence } from "./evidence.js";
+import { hashAnalysisValue } from "./validation.js";
+import { claimAutomaticStudyAnalysis, readAutomaticStudyAnalysisPrepared, requestAutomaticStudyAnalysisCancellationPrepared, } from "./job.js";
+import { ANALYSIS_ID_PATTERN } from "./types.js";
+import { readStudyAnalysisVersion } from "./store.js";
+import { readStudyAnalysisExecution } from "./store-executions.js";
+import { physicalCwdOf, resolvePhysicalCwd } from "../run/paths.js";
+const CANCELLATION_POLL_MS = 250;
+// Well inside AUTOMATIC_ANALYSIS_STALE_MS, so a live owner never reads as stale.
+const HEARTBEAT_MS = 5000;
+const exactId = (runId) => runId !== "latest" && ANALYSIS_ID_PATTERN.test(runId);
+const skipped = (reason) => ({ state: "skipped", reason });
+function hasParticipantEvidence(bundle) {
+    return bundle.streams.some((stream) => {
+        // Terminal commands and transcript messages also include launcher output.
+        // Fresh producers count recognized participant runtime items separately.
+        if (stream.actor?.lane === "terminal")
+            return (stream.actor.counts.runtimeParticipantItems ?? 0) > 0;
+        return stream.actor?.items.some((item) => ["screenshot", "ui_action", "command", "tool_call", "file_change", "approval"].includes(item.kind) ||
+            (["message", "reasoning"].includes(item.kind) && !!item.text?.trim()));
+    });
+}
+/** Small read-only TUI/CLI projection. Neither this nor Observer can resume a job. */
+export async function readAutomaticStudyAnalysis(cwd, runId) {
+    if (!exactId(runId))
+        return undefined;
+    const prepared = await resolveRunPath(await resolvePhysicalCwd(cwd), runId).catch(() => null);
+    return prepared ? readAutomaticStudyAnalysisPrepared(prepared) : undefined;
+}
+export async function requestAutomaticStudyAnalysisCancellation(cwd, runId) {
+    if (!exactId(runId))
+        return { requested: false, reason: "AUTOMATIC_ANALYSIS_SOURCE_UNAVAILABLE" };
+    const prepared = await resolveRunPath(await resolvePhysicalCwd(cwd), runId).catch(() => null);
+    return prepared
+        ? requestAutomaticStudyAnalysisCancellationPrepared(prepared)
+        : { requested: false, reason: "AUTOMATIC_ANALYSIS_SOURCE_UNAVAILABLE" };
+}
+/** The job reason for an analysis that reached a status. */
+function statusReason(result) {
+    if (result.reused)
+        return "AUTOMATIC_ANALYSIS_REUSED";
+    if (result.status === "partial") {
+        if (result.error?.code === "analysis_admission_estimate_exceeded")
+            return "AUTOMATIC_ANALYSIS_ADMISSION_EXCEEDED";
+        return result.ok ? "AUTOMATIC_ANALYSIS_LIMITATIONS" : "AUTOMATIC_ANALYSIS_FAILED";
+    }
+    if (result.status === "failed")
+        return "AUTOMATIC_ANALYSIS_FAILED";
+    if (result.status === "cancelled")
+        return "AUTOMATIC_ANALYSIS_CANCELLED";
+    return null;
+}
+function outcomeOf(result) {
+    if (result.error?.code === "ANALYSIS_PUBLICATION_FAILED")
+        return { state: "failed", reason: "AUTOMATIC_ANALYSIS_PUBLICATION_FAILED", result };
+    if (result.error?.code?.startsWith("analysis_codex_"))
+        return { state: "failed", reason: "AUTOMATIC_ANALYSIS_CODEX_UNAVAILABLE", result };
+    if (result.status)
+        return { state: result.status, result, reason: statusReason(result) };
+    const code = result.error?.code;
+    if (code === "ANALYSIS_CANCELLED")
+        return { state: "cancelled", reason: "AUTOMATIC_ANALYSIS_CANCELLED", result };
+    if (code === "ANALYSIS_API_KEY_MISSING")
+        return { ...skipped("AUTOMATIC_ANALYSIS_KEY_MISSING"), result };
+    if (code === "ANALYSIS_BUSY")
+        return { ...skipped("AUTOMATIC_ANALYSIS_BUSY"), result };
+    if (code === "ANALYSIS_HISTORY_UNAVAILABLE")
+        return { ...skipped("AUTOMATIC_ANALYSIS_STORAGE_UNAVAILABLE"), result };
+    if (code === "ANALYSIS_CONFIG_INVALID" ||
+        code === "ANALYSIS_QUESTION_UNSAFE" ||
+        code?.startsWith("analysis_")) {
+        return { ...skipped("AUTOMATIC_ANALYSIS_ADMISSION_REFUSED"), result };
+    }
+    return { state: "unknown", reason: "AUTOMATIC_ANALYSIS_OUTCOME_UNKNOWN", result };
+}
+/**
+ * Read the finished source before claiming the run's one job, so a claim is never consumed while a
+ * producer is still writing. Returns a skip outcome, or the participant-evidence flag and the
+ * config the job binds (a defaulted output limit may grow within the admission budget).
+ */
+async function readAutomaticSource(cwd, prepared, configInput, deps, hasKey) {
+    let config = configInput;
+    try {
+        const bytes = await readCompletedAnalysisSource(cwd, prepared);
+        const bundle = JSON.parse(bytes.toString("utf8"));
+        if (bundle.streams.some((stream) => stream.actor?.stopCause === "harness_aborted"))
+            return skipped("AUTOMATIC_ANALYSIS_ACTOR_CANCELLED");
+        const participantEvidence = hasParticipantEvidence(bundle);
+        // Bind the permanent job claim to the actual configuration before dispatch.
+        // Missing-key/no-evidence skips don't need to read captured image bytes.
+        if (config.provider !== "codex" &&
+            deps.preferLargerOutput &&
+            (!deps.defaultRequest || participantEvidence) &&
+            hasKey) {
+            config = preferLargerAnalysisOutput(await captureEvidence(prepared, bytes), config);
+        }
+        return { participantEvidence, config };
+    }
+    catch {
+        return skipped("AUTOMATIC_ANALYSIS_SOURCE_UNAVAILABLE");
+    }
+}
+/**
+ * Bind the job's terminal metadata to the exact safely published execution. Reads never promote a
+ * completed-looking sidecar without rechecking these bindings. Null when storage failed.
+ */
+async function persistOutcome(job, prepared, outcome) {
+    try {
+        const analysisId = outcome.result?.analysisId;
+        const [entry, receipt] = analysisId
+            ? await Promise.all([
+                readStudyAnalysisVersion(prepared, analysisId),
+                readStudyAnalysisExecution(prepared, analysisId),
+            ])
+            : [null, null];
+        await job.update({
+            state: outcome.state,
+            reason: outcome.reason,
+            analysisId: analysisId ?? null,
+            ...(receipt === null
+                ? {}
+                : {
+                    sourceRunSha256: receipt.sourceRunSha256,
+                    inputDigest: receipt.inputDigest,
+                    receiptSha256: hashAnalysisValue(receipt),
+                }),
+            ...(entry?.analysis ? { analysisSha256: hashAnalysisValue(entry.analysis) } : {}),
+        });
+        const persisted = await readAutomaticStudyAnalysisPrepared(prepared);
+        return persisted?.state === "unknown"
+            ? { ...outcome, state: "unknown", reason: persisted.reason }
+            : outcome;
+    }
+    catch {
+        return null;
+    }
+}
+/** One permanent claim per completed run, consumed even when preparation/cancellation fails.
+ * Only the original producer calls this after all recording writes return.
+ * No file reader, restart recovery, Observer poll or export calls this function. */
+export async function runAutomaticStudyAnalysis(cwdInput, runId, configInput, deps = {}) {
+    if (!exactId(runId))
+        return skipped("AUTOMATIC_ANALYSIS_SOURCE_UNAVAILABLE");
+    let cwd = path.resolve(cwdInput);
+    const prepared = await resolveAnalysisRun(cwd, runId, deps.expectedRun).catch(() => null);
+    if (!prepared)
+        return skipped("AUTOMATIC_ANALYSIS_SOURCE_UNAVAILABLE");
+    cwd = physicalCwdOf(prepared);
+    const hasKey = Boolean((deps.apiKey ?? process.env.OPENAI_API_KEY)?.trim());
+    const source = await readAutomaticSource(cwd, prepared, structuredClone(configInput), deps, hasKey);
+    if ("state" in source)
+        return source;
+    const { participantEvidence } = source;
+    let config = source.config;
+    // The claim digest must cover the Codex release that will run.
+    if (config.provider === "codex" && (deps.detectCodexCliVersion || !deps.codexProvider))
+        config = await (await import("./restricted-codex.js")).bindCodexAnalysisCliVersion(config, deps.detectCodexCliVersion);
+    let job;
+    try {
+        const claimed = await claimAutomaticStudyAnalysis(prepared, {
+            configDigest: hashAnalysisValue(config),
+            promptVersion: ANALYSIS_PROMPT_VERSION,
+        });
+        if (!claimed)
+            return skipped("AUTOMATIC_ANALYSIS_ALREADY_REQUESTED");
+        job = claimed;
+    }
+    catch {
+        return { state: "unknown", reason: "AUTOMATIC_ANALYSIS_STORAGE_UNAVAILABLE" };
+    }
+    const controller = new AbortController();
+    const signal = deps.signal
+        ? AbortSignal.any([deps.signal, controller.signal])
+        : controller.signal;
+    let polling = false;
+    let storageFailed = false;
+    let cancellationFailed = false;
+    const poll = async () => {
+        if (polling)
+            return;
+        polling = true;
+        try {
+            if (await job.cancellationRequested())
+                controller.abort();
+        }
+        catch {
+            cancellationFailed = true;
+            controller.abort();
+        }
+        finally {
+            polling = false;
+        }
+    };
+    const cancellationTimer = setInterval(() => {
+        void poll();
+    }, CANCELLATION_POLL_MS);
+    cancellationTimer.unref();
+    const heartbeat = setInterval(() => {
+        void job.touch().catch(() => {
+            storageFailed = true;
+            controller.abort();
+        });
+    }, HEARTBEAT_MS);
+    heartbeat.unref();
+    let outcome;
+    try {
+        await poll();
+        const missingKey = config.provider !== "codex" && !hasKey;
+        if (deps.defaultRequest === true && (missingKey || !participantEvidence)) {
+            outcome = signal.aborted
+                ? { state: "cancelled", reason: "AUTOMATIC_ANALYSIS_CANCELLED" }
+                : skipped(missingKey
+                    ? "AUTOMATIC_ANALYSIS_KEY_MISSING"
+                    : "AUTOMATIC_ANALYSIS_NO_PARTICIPANT_EVIDENCE");
+        }
+        else {
+            const result = await analyzeRun(cwd, runId, { config }, {
+                ...deps,
+                signal,
+                codexCliVersionBound: true,
+                expectedRun: prepared,
+                analysisId: job.attemptId,
+                beforeDispatch: async (context) => {
+                    if (await job.cancellationRequested())
+                        controller.abort();
+                    if (signal.aborted)
+                        return;
+                    await job.update({
+                        state: "running",
+                        analysisId: context.id,
+                        startedAt: new Date().toISOString(),
+                        sourceRunSha256: context.sourceRunSha256,
+                        inputDigest: context.inputDigest,
+                    });
+                },
+            });
+            outcome = outcomeOf(result);
+        }
+        if (cancellationFailed)
+            outcome = {
+                ...outcome,
+                state: "unknown",
+                reason: "AUTOMATIC_ANALYSIS_CANCELLATION_UNAVAILABLE",
+            };
+        if (storageFailed)
+            outcome = { ...outcome, state: "unknown", reason: "AUTOMATIC_ANALYSIS_STORAGE_UNAVAILABLE" };
+    }
+    catch {
+        outcome = { state: "unknown", reason: "AUTOMATIC_ANALYSIS_OUTCOME_UNKNOWN" };
+    }
+    finally {
+        clearInterval(cancellationTimer);
+        clearInterval(heartbeat);
+    }
+    const persisted = await persistOutcome(job, prepared, outcome);
+    if (persisted === null)
+        return { ...outcome, state: "unknown", reason: "AUTOMATIC_ANALYSIS_STORAGE_UNAVAILABLE" };
+    outcome = persisted;
+    // The service may render while this owner is still running. Freeze the final
+    // job projection for direct file opening too, including no-request outcomes.
+    // A failed refresh must never erase the durable outcome or measured usage.
+    if (!(await refreshObserver(cwd, runId, prepared)) && outcome.result)
+        outcome = {
+            ...outcome,
+            result: {
+                ...outcome.result,
+                warnings: [
+                    ...outcome.result.warnings,
+                    "Automatic analysis status was saved, but Observer could not be refreshed. Run humanish observe again.",
+                ],
+            },
+        };
+    return outcome;
+}

package/dist/analysis/codex-config.d.ts

@@ -0,0 +1,8 @@
+import type { CodexAnalysisIdentity, AnalysisConfig } from "./types.js";
+export declare const CODEX_ANALYSIS_MODEL: "gpt-6-astra";
+/** Before dispatch, analysis replaces the default release with the detected one. */
+export declare function codexAnalysisIdentity(model: string, cliVersion?: string): CodexAnalysisIdentity;
+/** Execution admission: the identity must name a release qualified on this host. */
+export declare function validCodexAnalysisConfig(config: AnalysisConfig, platform?: NodeJS.Platform, arch?: string): boolean;
+/** Reading historical artifacts never inserts defaults or selects a launch policy. */
+export declare function validStoredCodexAnalysisConfig(config: AnalysisConfig): boolean;

package/dist/analysis/codex-config.js

@@ -0,0 +1,69 @@
+import { RECORDED_CODEX_CLI_VERSIONS } from "../actors/contract.js";
+import { defaultCodexCliVersion, qualifiedCodexCliVersions, } from "../actors/codex/qualified-versions.js";
+import { RESTRICTED_CODEX_ANALYSIS_IDENTITY, RESTRICTED_CODEX_ANALYSIS_MODELS, } from "../actors/codex/restricted-policy.js";
+/** This account route is qualified against per-host CLI releases, one model and one tool policy. */
+const CODEX_ANALYSIS_TOOL_POLICY = RESTRICTED_CODEX_ANALYSIS_IDENTITY.toolPolicy;
+export const CODEX_ANALYSIS_MODEL = RESTRICTED_CODEX_ANALYSIS_MODELS[0];
+const CODEX_ANALYSIS_EFFORT = RESTRICTED_CODEX_ANALYSIS_IDENTITY.reasoningEffort;
+function identityFor(profile) {
+    return {
+        transport: "codex-app-server",
+        authentication: "chatgpt-account",
+        billing: "account-unknown",
+        requestedModel: profile.model,
+        resolvedModel: profile.model,
+        reasoningEffort: profile.reasoningEffort,
+        toolPolicy: profile.toolPolicy,
+        cliVersion: profile.cliVersion,
+    };
+}
+/** Before dispatch, analysis replaces the default release with the detected one. */
+export function codexAnalysisIdentity(model, cliVersion = defaultCodexCliVersion()) {
+    return identityFor({
+        model,
+        reasoningEffort: CODEX_ANALYSIS_EFFORT,
+        toolPolicy: CODEX_ANALYSIS_TOOL_POLICY,
+        cliVersion,
+    });
+}
+/** Reader profiles are append-only. A new launch qualification must not invalidate a saved report. */
+const storedProfiles = RECORDED_CODEX_CLI_VERSIONS.map((cliVersion) => ({
+    cliVersion,
+    toolPolicy: "restricted-codex-v1",
+    model: "gpt-6-astra",
+    reasoningEffort: "low",
+}));
+function matchesProfile(config, expected) {
+    if (config.provider !== "codex")
+        return false;
+    return (Object.keys(config).every((key) => [
+        "provider",
+        "model",
+        "question",
+        "maxCostUsd",
+        "timeoutMs",
+        "maxOutputTokens",
+        "identity",
+    ].includes(key)) &&
+        config.model === expected.requestedModel &&
+        config.maxCostUsd === null &&
+        config.maxOutputTokens === null &&
+        config.identity !== undefined &&
+        config.identity !== null &&
+        typeof config.identity === "object" &&
+        Object.keys(config.identity).length === Object.keys(expected).length &&
+        Object.entries(expected).every(([key, value]) => config.identity[key] === value));
+}
+/** Execution admission: the identity must name a release qualified on this host. */
+export function validCodexAnalysisConfig(config, platform = process.platform, arch = process.arch) {
+    if (config.provider !== "codex")
+        return false;
+    const cliVersion = config.identity?.cliVersion;
+    return (config.model === CODEX_ANALYSIS_MODEL &&
+        qualifiedCodexCliVersions(platform, arch).some((version) => version === cliVersion) &&
+        matchesProfile(config, codexAnalysisIdentity(config.model, cliVersion)));
+}
+/** Reading historical artifacts never inserts defaults or selects a launch policy. */
+export function validStoredCodexAnalysisConfig(config) {
+    return storedProfiles.some((profile) => matchesProfile(config, identityFor(profile)));
+}

package/dist/analysis/evidence-sources.d.ts

@@ -0,0 +1,23 @@
+import type { RunBundle } from "../run/bundle.js";
+import type { RunStream } from "../run/streams.js";
+import { type AnalysisParticipantInput, type CaptureVersion } from "./types.js";
+export declare function hasUnmappedCaptures(stream: RunStream): boolean;
+export declare function boundedText(value: string, maxBytes: number): string;
+export declare function participantAssignment(stream: RunStream, captureVersion?: CaptureVersion): string | null;
+export declare function participantSource(stream: RunStream, captureVersion?: CaptureVersion): AnalysisParticipantInput;
+export interface SourceEntry {
+    eventId: string;
+    kind: string;
+    text: string;
+    quoteEligible: boolean;
+    at: string | null;
+    elapsedMs: number | null;
+    frame: number | null;
+    capturePath: string | null;
+    captureDeclared: boolean;
+    failed: boolean;
+}
+export declare function sourceEntries(bundle: RunBundle, stream: RunStream, captureVersion?: CaptureVersion): SourceEntry[];
+/** Max-min allocation; stable ID order breaks a remainder tie by at most one slot. */
+export declare function fairShares(budget: number, capacities: number[]): number[];
+export declare function sourceOrder(entries: SourceEntry[], capturesOnly: boolean): SourceEntry[];

package/dist/analysis/evidence-sources.js

@@ -0,0 +1,251 @@
+import { receivingAnalysisContext } from "../comms/receiving-evidence.js";
+import { eventRecordIdOf, recordIdOf, streamParticipantIdOf } from "../run/participant-records.js";
+import { cuaGoalSource } from "../actors/goal-source.js";
+import { isRecord } from "../run/type-guards.js";
+import { ACTION_CAPTURE_VERSION, } from "./types.js";
+import { decodesToPlainRelativePath, isStudyEvidencePath } from "../run/study-files.js";
+// How a run bundle becomes analysis sources: each participant's recorded provenance and assignment,
+// the evidence entries its trace offers, and the order in which entries are admitted under the
+// count and byte budgets. captureEvidence selects from these, and validateAnalysisEvidence
+// re-derives them to check a stored analysis against its run.
+const stamp = (value) => typeof value === "string" && Number.isFinite(Date.parse(value))
+    ? new Date(value).toISOString()
+    : null;
+const itemText = (item) => ["message", "reasoning"].includes(item.kind) && item.text !== undefined
+    ? item.text
+    : [item.title, item.text].filter((entry) => entry !== undefined && entry !== "").join("\n");
+const itemsFor = (stream) => stream.actor?.items ?? [];
+const isCaptureItem = (item, captureVersion) => item.kind === "screenshot" ||
+    (captureVersion === ACTION_CAPTURE_VERSION && item.kind === "ui_action");
+export function hasUnmappedCaptures(stream) {
+    const items = itemsFor(stream);
+    const paths = new Set(items.flatMap((item) => isCaptureItem(item, 2) && typeof item.screenshotRef?.path === "string"
+        ? [item.screenshotRef.path]
+        : []));
+    // Presentation URLs use Observer-relative paths. They cannot manufacture an
+    // event/frame, but a declared capture outside the trace must limit coverage.
+    const previews = [
+        stream.ui?.screenshotUrl,
+        stream.embed?.kind === "screenshot" ? stream.embed.url : undefined,
+    ];
+    return ((Array.isArray(stream.artifacts) &&
+        stream.artifacts.some((artifact) => artifact?.kind === "screenshot" && !paths.has(artifact.path))) ||
+        previews.some((ref) => typeof ref === "string" && !paths.has(ref) && !paths.has(ref.replace(/^\.\.\//, ""))) ||
+        items.some((item) => typeof item.screenshotRef?.path === "string" && !paths.has(item.screenshotRef.path)));
+}
+export function boundedText(value, maxBytes) {
+    if (Buffer.byteLength(value) <= maxBytes)
+        return value;
+    let output = "";
+    let bytes = 0;
+    for (const char of value) {
+        const size = Buffer.byteLength(char);
+        if (bytes + size > maxBytes)
+            break;
+        output += char;
+        bytes += size;
+    }
+    return output;
+}
+// Count the same frame declarations as Observer even when analysis omits their bytes.
+function isObserverCapturePath(value) {
+    if (/^data:image\/(?:png|jpeg|gif|webp);base64,[A-Za-z0-9+/]+={0,2}$/.test(value))
+        return true;
+    return decodesToPlainRelativePath(value, 8192, /^[\\/]|[\\\u0000-\u001f\u007f]|^[a-z][a-z\d+.-]*:/i);
+}
+export function participantAssignment(stream, captureVersion) {
+    if (stream.assignment === undefined)
+        return captureVersion === ACTION_CAPTURE_VERSION &&
+            stream.actor?.lane === "scripted-browser" &&
+            typeof stream.ui?.intent === "string" &&
+            stream.ui.intent.trim()
+            ? stream.ui.intent
+            : null;
+    return [
+        stream.assignment.mission,
+        stream.assignment.focus,
+        ...(stream.assignment.tasks ?? []).map((task) => `Task ${JSON.stringify(task.id)}: ${task.goal}`),
+    ]
+        .filter((entry) => typeof entry === "string")
+        .join("\n");
+}
+export function participantSource(stream, captureVersion) {
+    const assignment = participantAssignment(stream, captureVersion);
+    const actor = stream.actor;
+    return {
+        streamId: stream.id,
+        label: boundedText(stream.label, 1000),
+        assignment: assignment === null ? null : boundedText(assignment, 8000),
+        recordedStatus: stream.status,
+        recordedReason: actor?.reason === undefined ? null : boundedText(actor.reason, 4000),
+        provenance: {
+            actorStatus: actor?.status ?? null,
+            completionReason: actor?.completionReason ?? null,
+            stopCause: actor?.stopCause ?? null,
+            goalSource: cuaGoalSource(actor, stream.status) ?? null,
+            declaredOutcome: actor?.declaredOutcome ?? null,
+            taskOutcomes: actor?.taskFunnel === undefined
+                ? null
+                : actor.taskFunnel.tasks.map((task) => ({
+                    taskId: task.id,
+                    completed: task.completed,
+                    observable: task.observable,
+                    inputsObserved: task.inputsObserved ?? null,
+                    turn: task.turn ?? null,
+                })),
+        },
+    };
+}
+export function sourceEntries(bundle, stream, captureVersion) {
+    const items = itemsFor(stream);
+    // Absent version retains the exact legacy mapping used by saved 0.89.1 analyses.
+    // V2 follows the actor contract: a scripted action can carry its own capture.
+    const captures = items.filter((item) => isCaptureItem(item, captureVersion) &&
+        isRecord(item.screenshotRef) &&
+        typeof item.screenshotRef.path === "string" &&
+        isObserverCapturePath(item.screenshotRef.path));
+    const frameIds = new Set(captures.map((item) => item.id));
+    const firstAt = stamp(captures[0]?.at);
+    let frame = -1;
+    const entries = [];
+    if (captureVersion === ACTION_CAPTURE_VERSION && bundle.commsReceiving) {
+        entries.push({
+            eventId: `comms-receiving-${stream.id}`,
+            kind: "harness:email_receiving",
+            text: receivingAnalysisContext(bundle.commsReceiving, streamParticipantIdOf(stream)),
+            quoteEligible: false,
+            at: null,
+            elapsedMs: null,
+            frame: null,
+            capturePath: null,
+            captureDeclared: false,
+            failed: bundle.commsReceiving.limitations.length > 0 ||
+                bundle.commsReceiving.participants.some((p) => p.limitations.length > 0),
+        });
+    }
+    for (const item of items) {
+        const capturePath = isCaptureItem(item, captureVersion) &&
+            isRecord(item.screenshotRef) &&
+            typeof item.screenshotRef.path === "string" &&
+            isStudyEvidencePath(item.screenshotRef.path)
+            ? item.screenshotRef.path
+            : null;
+        if (frameIds.has(item.id))
+            frame++;
+        const at = stamp(item.at);
+        const delta = at !== null && firstAt !== null ? Date.parse(at) - Date.parse(firstAt) : null;
+        entries.push({
+            eventId: item.id,
+            kind: item.kind,
+            text: itemText(item),
+            quoteEligible: ["message", "reasoning"].includes(item.kind) && typeof item.text === "string",
+            at,
+            elapsedMs: delta !== null && delta >= 0 ? delta : null,
+            frame: captures.length > 0 ? Math.max(0, frame) : null,
+            capturePath,
+            captureDeclared: item.kind === "screenshot" ||
+                (captureVersion === ACTION_CAPTURE_VERSION &&
+                    item.kind === "ui_action" &&
+                    item.screenshotRef !== undefined),
+            failed: ["failed", "blocked", "timed_out"].includes(item.status ?? ""),
+        });
+    }
+    const runEventIds = new Set();
+    for (const event of bundle.events.filter((entry) => entry.streamId === stream.id ||
+        (entry.streamId === undefined && eventRecordIdOf(entry) === recordIdOf(stream)))) {
+        if (runEventIds.has(event.id))
+            throw new Error("ANALYSIS_SOURCE_EVENT_DUPLICATE");
+        runEventIds.add(event.id);
+        entries.push({
+            eventId: event.id,
+            kind: `run_event:${event.type}`,
+            text: event.message,
+            quoteEligible: false,
+            at: stamp(event.at),
+            elapsedMs: null,
+            frame: null,
+            capturePath: null,
+            captureDeclared: false,
+            failed: event.level === "error",
+        });
+    }
+    return entries;
+}
+/** Max-min allocation; stable ID order breaks a remainder tie by at most one slot. */
+export function fairShares(budget, capacities) {
+    const shares = capacities.map(() => 0);
+    let active = capacities
+        .map((capacity, index) => ({ capacity, index }))
+        .filter(({ capacity }) => capacity > 0);
+    while (budget > 0 && active.length > 0) {
+        const share = Math.max(1, Math.floor(budget / active.length));
+        for (const { capacity, index } of active) {
+            const granted = Math.min(capacity - shares[index], share, budget);
+            shares[index] += granted;
+            budget -= granted;
+        }
+        active = active.filter(({ capacity, index }) => shares[index] < capacity);
+    }
+    return shares;
+}
+/** End, start, then successively bisect the whole interval; no prefix sampling. */
+function spreadOrder(entries) {
+    if (entries.length < 2)
+        return entries;
+    const result = [entries.at(-1), entries[0]];
+    const ranges = [[0, entries.length - 1]];
+    for (let cursor = 0; cursor < ranges.length; cursor++) {
+        const [left, right] = ranges[cursor];
+        if (right - left < 2)
+            continue;
+        const middle = Math.floor((left + right) / 2);
+        result.push(entries[middle]);
+        ranges.push([left, middle], [middle, right]);
+    }
+    return result;
+}
+export function sourceOrder(entries, capturesOnly) {
+    const candidates = capturesOnly ? entries.filter((entry) => entry.capturePath !== null) : entries;
+    const ordered = new Set();
+    const admit = (entry) => {
+        if (entry && (!capturesOnly || entry.capturePath !== null))
+            ordered.add(entry);
+    };
+    // Actor endings precede appended run bookkeeping when text slots are scarce.
+    if (!capturesOnly)
+        admit(entries.findLast((entry) => !entry.kind.startsWith("run_event:")));
+    admit(candidates.at(-1));
+    admit(candidates[0]);
+    const afterCapture = [];
+    let nextCapture;
+    for (let index = entries.length - 1; index >= 0; index--) {
+        const entry = entries[index];
+        afterCapture[index] = nextCapture;
+        if (entry.capturePath !== null)
+            nextCapture = entry;
+    }
+    let beforeCapture;
+    const failureContext = [];
+    for (let index = 0; index < entries.length; index++) {
+        const entry = entries[index];
+        if (entry.failed) {
+            for (const context of [entry, afterCapture[index], beforeCapture, entries[index + 1]]) {
+                if (context)
+                    failureContext.push(context);
+            }
+        }
+        if (entry.capturePath !== null)
+            beforeCapture = entry;
+    }
+    // Explicit failure status/level is source metadata, not a keyword diagnosis.
+    // Spread among failures as well: many early failures cannot hide the last one.
+    for (const entry of spreadOrder(failureContext))
+        admit(entry);
+    // A final scroll or navigation can move the result out of view. Keep its
+    // preceding capture as ending context, regardless of the reported outcome.
+    if (capturesOnly)
+        admit(candidates.at(-2));
+    for (const entry of spreadOrder(candidates))
+        admit(entry);
+    return [...ordered];
+}

package/dist/analysis/evidence.d.ts

@@ -0,0 +1,18 @@
+import { type PreparedRunArtifactPaths } from "../run/paths.js";
+import { type AnalysisArtifact, type AnalysisInput } from "./types.js";
+export declare const EVIDENCE_LIMITS: Readonly<{
+    participants: 16;
+    evidence: 800;
+    captures: 40;
+    textBytes: number;
+    imageBytes: number;
+    totalImageBytes: number;
+    sourceBytes: number;
+}>;
+export type EvidenceLimits = {
+    [Key in keyof typeof EVIDENCE_LIMITS]?: number;
+};
+/** Select once from retained source. Models receive no filesystem or network resolver. */
+export declare function captureEvidence(prepared: PreparedRunArtifactPaths, bundleBytes: Buffer, requested?: EvidenceLimits): Promise<AnalysisInput>;
+/** Validate exact source membership before any stored path may be read. */
+export declare function validateAnalysisEvidence(prepared: PreparedRunArtifactPaths, artifact: AnalysisArtifact, bundleBytes: Buffer): Promise<void>;