humanish 0.124.0 → 0.126.0

package/dist/actors/contract.d.ts

@@ -37,12 +37,21 @@ export type ParticipantDeclaredOutcome = "reached" | "not_reached" | "blocked";
 export declare const PARTICIPANT_OUTCOME_STATUSES: readonly ActorStatus[];
 /** Optional precise interruption cause; completionReason and status retain their original meaning.
  *  One list, so the analysis schema and the diagnostics projection cannot drift from the trace. */
-export declare const ACTOR_STOP_CAUSES: readonly ["provider_output_limit", "provider_token_limit", "time_limit", "spend_limit", "study_spend_limit", "adapter_limit", "provider_incomplete", "provider_status", "provider_refused_prompt", "harness_aborted", "usage_unreported", "scheduled_end"];
+export declare const ACTOR_STOP_CAUSES: readonly ["provider_output_limit", "provider_token_limit", "time_limit", "spend_limit", "study_spend_limit", "adapter_limit", "provider_incomplete", "provider_status", "provider_refused_prompt", "harness_aborted", "usage_unreported", "scheduled_end", "session_cap"];
 export type ActorStopCause = (typeof ACTOR_STOP_CAUSES)[number];
 export type ActorCompletionReason = "goal_satisfied" | "turn_completed" | "gave_up" | "blocked_approval" | "timed_out" | "budget_reached" | "actor_error" | "step_failed" | "harness_error";
 type ActorRunKind = "code" | "computer-use" | "scripted-browser" | "terminal";
 type ActorProtocol = "json-rpc" | "json-stream" | "cua-loop" | "scripted-steps" | "terminal-exec";
 export type ActorTraceItemKind = "message" | "reasoning" | "tool_call" | "command" | "file_change" | "approval" | "screenshot" | "ui_action" | "plan" | "notice";
+/**
+ * Where a participant's browser was at one observation: the URL's origin and its path, redacted
+ * (src/evidence/trace-page.ts). No query string, fragment or user info. A non-web URL keeps only
+ * its scheme, as `{ origin: "about:", path: "" }`.
+ */
+export interface TracePage {
+    origin: string;
+    path: string;
+}
 export interface ActorTraceItem {
     id: string;
     kind: ActorTraceItemKind;
@@ -74,6 +83,9 @@ export interface ActorTraceItem {
         x: number;
         y: number;
     };
+    /** On a computer-use `screenshot` item: the page that observation was on. Additive: absent when
+     *  the observation read no URL, on other producers and in older bundles. */
+    page?: TracePage;
 }
 export interface ActorCapabilities {
     headless: boolean;
@@ -338,19 +350,24 @@ export interface ActorTrace {
      */
     taskFunnel?: TaskFunnel;
     /**
-     * Additive + optional: the outcome the participant declared on its final turn, when its
-     * provider's reply carries the field. Absent on free-text providers and on every older bundle.
-     * The route reads this before it reads the closing paragraph; three regex patches in one month
-     * each fixed a false refusal and each left the next shape unhandled.
+     * Additive + optional: the outcome the participant declared, in its provider's outcome field or
+     * in the fixed first line its prompt asks for. It comes from its last message when it ended the
+     * session itself, and from its accepted closing report at a scheduled end or a session cap.
+     * Absent when it declared none, after a stop condition or a dwell window, and on every older
+     * bundle. The route reads a declared `reached` or `blocked` before it reads the closing
+     * paragraph; three regex patches in one month each fixed a false refusal and each left the next
+     * shape unhandled. A declared `not_reached` leaves the paragraph to say whether a blocker
+     * stopped the participant.
      */
     declaredOutcome?: ParticipantDeclaredOutcome;
     /**
      * The read-only closing request: a closing report after a harness-owned stop (`stop_when`,
-     * `dwell`, `scheduled_end`), or impressions only after the participant ended the session itself
-     * (`participant_end`, never with `report`). Does not change task outcomes or permit actions.
+     * `dwell`, `scheduled_end`, `session_cap`), or impressions only after the participant ended the
+     * session itself (`participant_end`, never with `report`). Does not change task outcomes or
+     * permit actions.
      */
     debrief?: {
-        trigger: "stop_when" | "dwell" | "scheduled_end" | "participant_end";
+        trigger: "stop_when" | "dwell" | "scheduled_end" | "session_cap" | "participant_end";
         status: "completed" | "skipped" | "failed";
         reason: string;
         /** Absent if no request was made; false means token accounting is incomplete. */
@@ -366,6 +383,12 @@ export interface ActorTrace {
      */
     impressions?: ParticipantImpressions;
     items: ActorTraceItem[];
+    /**
+     * Additive + optional: the page of the computer-use session's last observation, the closing
+     * task observation included. Absent when that observation read no URL, so a failed read never
+     * repeats an earlier page, and on other producers and older bundles.
+     */
+    finalPage?: TracePage;
     tokenUsage?: ActorTokenUsage;
     /** A stalled or adapter-reported ambiguous interaction may have additional unreported usage.
      *  Known tokenUsage remains usable as a partial total. Absence is not proof of completeness. */

package/dist/actors/contract.js

@@ -56,6 +56,9 @@ export const ACTOR_STOP_CAUSES = [
     // The participant's scheduled end (participants[].endAfterMs) came. A planned end: the session
     // is goal_satisfied, and the closing report follows.
     "scheduled_end",
+    // The participant was still working at its session cap (participants[].maxSessionMs). A planned
+    // end, as scheduled_end is: the session is goal_satisfied, and the closing report follows.
+    "session_cap",
 ];
 /**
  * The oldest Codex CLI release a recorded account profile may name. Readers accept every stable

package/dist/actors/stop-cause.js

@@ -11,6 +11,7 @@ const labels = {
     provider_refused_prompt: "provider refused the prompt under its usage policy",
     harness_aborted: "stopped by harness",
     scheduled_end: "scheduled end",
+    session_cap: "session cap",
     unspecified_limit: "limit reached",
 };
 /** Shared wording for consumers that already hold a validated, finite stop cause. */

package/dist/analysis/evidence.js

@@ -3,7 +3,7 @@ import { createHash } from "node:crypto";
 import { screenshotEvidenceError } from "../evidence/image.js";
 import { runIdOf } from "../run/paths.js";
 import { isRecord } from "../run/type-guards.js";
-import { RUN_BUNDLE_FILE, RUN_BUNDLE_SCHEMA, RUN_BUNDLE_V1_SCHEMA, } from "../run/bundle.js";
+import { isReadRunBundleSchema, RUN_BUNDLE_FILE } from "../run/bundle.js";
 import { loadStreamTraces } from "../run/stream-trace.js";
 import { ACTION_CAPTURE_VERSION, } from "./types.js";
 import { digestAnalysisInput, hashAnalysisValue, validateAnalysisInputMetadata, } from "./validation.js";
@@ -30,7 +30,7 @@ function parseSource(prepared, bytes) {
         throw new Error("ANALYSIS_SOURCE_TOO_LARGE");
     const value = JSON.parse(new TextDecoder("utf-8", { fatal: true }).decode(bytes));
     if (!isRecord(value) ||
-        (value.schema !== RUN_BUNDLE_SCHEMA && value.schema !== RUN_BUNDLE_V1_SCHEMA) ||
+        !isReadRunBundleSchema(value.schema) ||
         value.runId !== runIdOf(prepared) ||
         !Array.isArray(value.streams) ||
         value.streams.length > EVIDENCE_LIMITS.participants ||

package/dist/cli/commands/study.js

@@ -2,6 +2,8 @@ import { formatAutomaticAnalysisBudget } from "../../analysis/automatic-config.j
 import { resolve } from "node:path";
 import { Command, Option } from "commander";
 import { inspectStudyManifest, listStudyManifests } from "../../study/discover.js";
+import { describeTimeZones } from "../../study/plan-participants.js";
+import { plannedParticipants } from "../../study/warnings.js";
 import { runStudyPreflight, } from "../../study/preflight.js";
 import { applyEnvFileOption, CWD_OPTION_DESCRIPTION, DOTENV_OPTION_DESCRIPTION, dotenvPathOf, envFileAliasOption, JSON_OPTION_DESCRIPTION, parsePositiveInteger, writeResult, humanError, } from "../io.js";
 export function registerStudyCommands(parent, io) {
@@ -120,6 +122,7 @@ function formatStudyShowHuman(result) {
         ...(result.path ? [`path: ${result.path}`] : []),
         ...(result.origin ? [`origin: ${result.origin}`] : []),
         ...(config.subject.repos?.length ? [`repos: ${config.subject.repos.join(", ")}`] : []),
+        ...timeZoneLines(config),
         ...(result.personas ?? []).map((persona) => `persona ${persona.id}: ${persona.brief ? `authored context (before runtime additions)\n${persona.brief.text}` : "unresolved; id only"}`),
         ...result.warnings.map((warning) => `warning: ${warning}`),
     ].join("\n") + "\n");
@@ -145,3 +148,8 @@ function formatStudyCheckHuman(result) {
     ].join("\n") + "\n";
     return result.error === undefined ? stdout : { stdout, error: result.error };
 }
+/** The `time zones:` line, for a study whose participants declare a time zone. */
+function timeZoneLines(config) {
+    const zones = describeTimeZones(plannedParticipants(config));
+    return zones === undefined ? [] : [`time zones: ${zones}`];
+}

package/dist/evidence/redaction.d.ts

@@ -8,6 +8,7 @@ export declare const REDACTION_MARKERS: {
     readonly runtimePath: "[REDACTED_RUNTIME_PATH]";
     readonly promptText: "[REDACTED_PROMPT_TEXT]";
     readonly lobbyCode: "[REDACTED_LOBBY_CODE]";
+    readonly urlPart: "[REDACTED_URL_PART]";
 };
 /** Every pattern containsSensitive tests. A test pins each to ASCII, which scanEncodedText relies on. */
 export declare function sensitivePatterns(): readonly RegExp[];

package/dist/evidence/redaction.js

@@ -136,6 +136,7 @@ export const REDACTION_MARKERS = {
     runtimePath: "[REDACTED_RUNTIME_PATH]",
     promptText: "[REDACTED_PROMPT_TEXT]",
     lobbyCode: "[REDACTED_LOBBY_CODE]",
+    urlPart: "[REDACTED_URL_PART]",
 };
 const LOCAL_PATH_PATTERNS = [
     [/\/private\/var\/folders\/[^\s"'`<>)]*/g, REDACTION_MARKERS.localPath],

package/dist/evidence/trace-page.d.ts

@@ -0,0 +1,6 @@
+import type { TracePage } from "../actors/contract.js";
+/**
+ * The page of an observed URL, or undefined when there is none or the URL parser rejects it.
+ * `redact` is the trace's text redaction (the run's known-value scrub, then redactText).
+ */
+export declare function tracePage(url: string | undefined, redact: (text: string) => string): TracePage | undefined;

package/dist/evidence/trace-page.js

@@ -0,0 +1,90 @@
+import { readingsOf, scanEncodedText } from "./encoded-text.js";
+import { REDACTION_MARKERS } from "./redaction.js";
+// The page a computer-use observation was on, as a trace records it: the URL's origin and path,
+// with no query string, fragment or user info, and any path segment that can carry a credential or
+// an address withheld. See docs/contracts/schemas.md#actor-trace.
+const WEB_SCHEMES = new Set(["http:", "https:"]);
+// The longest path a page keeps, its truncation marker included.
+const MAX_PATH = 1024;
+const TRUNCATED = "[TRUNCATED]";
+// A percent-encoded unreserved character (a letter, digit, `-`, `.`, `_` or `~`) or `%` itself.
+// RFC 3986 section 2.3 says producers should not encode the first, and an encoded `%` is an
+// encoding nested in another, so either only hides text from a literal match: the run's
+// sandbox-id scrub, verify's raw-id check, a study secret's scrub.
+const ENCODED_TO_HIDE = /%(?:3[0-9]|4[1-9A-F]|5[0-9AF]|6[1-9A-F]|7[0-9AE]|2[5DE])/i;
+const EMAIL = /[^\s@/]@[^\s@/.]+\.[^\s@/]/;
+// 16 characters is the floor redactText uses for a credential parameter's value. Each open-ended
+// repeat is written `[...]{n}[...]*`, as in redaction.ts, so a megabyte path costs linear time.
+const TOKEN_RUN = /[A-Za-z0-9_-]{16}[A-Za-z0-9_-]*/g;
+const LETTER = /[A-Za-z]/;
+const DIGIT = /[0-9]/;
+/**
+ * A run of 16 or more letters, digits, `-` and `_` in which some piece between separators is 8 or
+ * more characters long and mixes letters and digits: UUIDs, hex digests, base64url tokens and
+ * sandbox ids. A slug's pieces are words or numbers, so `how-to-build-a-thing-2024` stays.
+ */
+function tokenShaped(text) {
+    for (const [run] of text.matchAll(TOKEN_RUN))
+        for (const piece of run.split(/[-_]/))
+            if (piece.length >= 8 && LETTER.test(piece) && DIGIT.test(piece))
+                return true;
+    return false;
+}
+/** A segment is withheld when any reading of it holds an address, a token or redactable text. */
+function withheld(segment, redact) {
+    if (ENCODED_TO_HIDE.test(segment))
+        return true;
+    return readingsOf(segment).some((reading) => EMAIL.test(reading) || tokenShaped(reading) || redact(reading) !== reading);
+}
+/**
+ * Each withheld segment as the marker, then the trace redaction over the whole path for patterns
+ * that span segments, then the cut. A path verify's trace scan would still read as sensitive or
+ * opaque is withheld whole, so a page never changes a run's grade.
+ */
+function redactPath(pathname, redact) {
+    const segments = pathname
+        .split("/")
+        .map((segment) => (withheld(segment, redact) ? REDACTION_MARKERS.urlPart : segment));
+    const redacted = redact(segments.join("/"));
+    // Cut after redaction: a cut first could shorten a token below the length the rules match.
+    const path = redacted.length > MAX_PATH
+        ? `${redacted.slice(0, MAX_PATH - TRUNCATED.length)}${TRUNCATED}`
+        : redacted;
+    const scan = scanEncodedText(path);
+    return scan.sensitive || scan.opaque ? REDACTION_MARKERS.urlPart : path;
+}
+/**
+ * The origin with each token-shaped host label withheld, since a tunnel or preview host can be as
+ * unguessable as a shared link, then through the trace redaction, which withholds a sandbox host
+ * whole.
+ */
+function redactOrigin(url, redact) {
+    if (url.hostname.startsWith("["))
+        return redact(url.origin);
+    const host = url.hostname
+        .split(".")
+        .map((label) => (tokenShaped(label) ? REDACTION_MARKERS.urlPart : label))
+        .join(".");
+    return redact(`${url.protocol}//${host}${url.port === "" ? "" : `:${url.port}`}`);
+}
+/**
+ * The page of an observed URL, or undefined when there is none or the URL parser rejects it.
+ * `redact` is the trace's text redaction (the run's known-value scrub, then redactText).
+ */
+export function tracePage(url, redact) {
+    if (url === undefined)
+        return undefined;
+    const parsed = URL.parse(url);
+    if (parsed === null)
+        return undefined;
+    // A non-web URL keeps its scheme only: a file: path or a data: payload never lands.
+    if (!WEB_SCHEMES.has(parsed.protocol))
+        return { origin: parsed.protocol, path: "" };
+    const origin = redactOrigin(parsed, redact);
+    const path = redactPath(parsed.pathname, redact);
+    // A study secret can span both parts, such as a whole invite link, which neither part holds.
+    const joined = `${origin}${path}`;
+    if (redact(joined) !== joined)
+        return { origin: REDACTION_MARKERS.urlPart, path: REDACTION_MARKERS.urlPart };
+    return { origin, path };
+}

package/dist/index.d.ts

@@ -8,6 +8,7 @@ export { parseStudy } from "./study/config.js";
 export { STUDY_SCHEMA } from "./study/types.js";
 export type { StudyConfig } from "./study/types.js";
 export { verifyRun } from "./verify/verify.js";
+export { loadRunBundle } from "./run/locate.js";
 export type { VerifyResult } from "./verify/verify.js";
 export { renderObserver } from "./observer/render.js";
 export type { ObserverResult } from "./observer/render.js";

package/dist/index.js

@@ -8,6 +8,7 @@ export { parseStudy } from "./study/config.js";
 export { STUDY_SCHEMA } from "./study/types.js";
 // Read a run.
 export { verifyRun } from "./verify/verify.js";
+export { loadRunBundle } from "./run/locate.js";
 export { renderObserver } from "./observer/render.js";
 // Bring a participant.
 export { runComputerUseLoop, stableProgressKey } from "./actors/computer-use/loop.js";

package/dist/observer/feed-cursors.d.ts

@@ -0,0 +1,14 @@
+import type { LiveItemsCursor } from "../run/live-items.js";
+import type { LiveItemsRead } from "../run/stream-trace.js";
+import type { ObserverItems } from "./participant-items.js";
+/**
+ * The prefixes a poll's `after` parameter says the page holds, by live file path. A parameter with
+ * a cursor that is not spelled as the server spells them, more than 10,000 cursors, or two for one
+ * file is ignored whole, so the page gets every list in full.
+ */
+export declare function parseFeedCursors(after: string | null): ReadonlyMap<string, LiveItemsCursor>;
+/**
+ * `items` with each live file's cursor on the entry of the stream it was joined into, and
+ * `liveAfter`, the page's cursor, where the entry's `liveActor` holds only the items past it.
+ */
+export declare function withFeedCursors(items: ObserverItems, live: readonly LiveItemsRead[]): ObserverItems;

package/dist/observer/feed-cursors.js

@@ -0,0 +1,61 @@
+// The cursors of the Observer's feed. A cursor is `<position>.<generation>.<items>.<bytes>`: the
+// live file live/<position>.<generation>.ndjson (src/run/live-items.ts names them) and the prefix of
+// it a page holds. Each feed response gives a running participant's cursor as `live`; the page sends
+// the cursors back in `after` and compares them only as strings, so a cursor has one spelling:
+// decimal integers without leading zeros.
+/** A live file's stem, `<position>.<generation>`, as isLiveItemsIndex accepts its path. */
+const LIVE_PATH = /^live\/([1-9]\d{0,5}\.[1-9]\d{0,8})\.ndjson$/;
+/** A cursor: the stem, then the line and byte counts. */
+const CURSOR = /^([1-9]\d{0,5}\.[1-9]\d{0,8})\.(0|[1-9]\d{0,15})\.(0|[1-9]\d{0,15})$/;
+/** More cursors than any page sends: a run has one live file per participant. */
+const MAX_CURSORS = 10_000;
+/**
+ * The prefixes a poll's `after` parameter says the page holds, by live file path. A parameter with
+ * a cursor that is not spelled as the server spells them, more than 10,000 cursors, or two for one
+ * file is ignored whole, so the page gets every list in full.
+ */
+export function parseFeedCursors(after) {
+    const cursors = new Map();
+    if (after === null || after === "")
+        return cursors;
+    const parts = after.split(",", MAX_CURSORS + 1);
+    if (parts.length > MAX_CURSORS)
+        return new Map();
+    for (const part of parts) {
+        const match = CURSOR.exec(part);
+        const path = `live/${match?.[1]}.ndjson`;
+        const cursor = { items: Number(match?.[2]), bytes: Number(match?.[3]) };
+        if (match === null ||
+            !Number.isSafeInteger(cursor.items) ||
+            !Number.isSafeInteger(cursor.bytes) ||
+            cursors.has(path))
+            return new Map();
+        cursors.set(path, cursor);
+    }
+    return cursors;
+}
+/** The cursor at `items` lines and `bytes` bytes into the live file at `path`. */
+function cursorText(path, position) {
+    const stem = LIVE_PATH.exec(path)?.[1];
+    if (stem === undefined)
+        throw new Error(`${path} is not a live file name.`);
+    return `${stem}.${position.items}.${position.bytes}`;
+}
+/**
+ * `items` with each live file's cursor on the entry of the stream it was joined into, and
+ * `liveAfter`, the page's cursor, where the entry's `liveActor` holds only the items past it.
+ */
+export function withFeedCursors(items, live) {
+    const streams = Object.assign(Object.create(null), items.streams);
+    for (const read of live) {
+        const entry = Object.hasOwn(streams, read.streamId) ? streams[read.streamId] : undefined;
+        if (entry === undefined || !Array.isArray(entry.liveActor))
+            continue;
+        streams[read.streamId] = {
+            ...entry,
+            live: cursorText(read.index.path, read.index),
+            ...(read.after === undefined ? {} : { liveAfter: cursorText(read.index.path, read.after) }),
+        };
+    }
+    return { ...items, streams };
+}

package/dist/observer/participant-items.d.ts

@@ -23,6 +23,13 @@ export interface ObserverItems {
         actor?: ActorTraceItem[];
         liveActor?: ActorTraceItem[];
         artifacts?: ObserverStream["artifacts"];
+        /**
+         * Where `liveActor` ends in the participant's live file, as a cursor the page sends back
+         * (src/observer/feed-cursors.ts). Only on a feed response, for a list read from a live file.
+         */
+        live?: string;
+        /** Set when `liveActor` holds only the items past this cursor, one the page sent. */
+        liveAfter?: string;
     }>;
 }
 /** The data as observer-data.json and the page's items carry it. */

package/dist/observer/pinned-files.d.ts

@@ -17,10 +17,13 @@ export interface PinnedDirectory {
 /**
  * The file's bytes, or null when it cannot be read under the root's checks. With `maxBytes`, a
  * file larger than that is refused from its opened size and the read stops there, so a large file
- * is never held in memory.
+ * is never held in memory. With `length`, only the file's first `length` bytes are read, or all of
+ * a shorter file; with `start` as well, the bytes from `start` to `length`.
  */
 export declare function readContainedFile(root: PinnedDirectory, filePathInput: string, options?: {
     maxBytes?: number;
+    length?: number;
+    start?: number;
 }): Promise<Buffer | null>;
 export declare function openContainedFile(root: PinnedDirectory, filePathInput: string): Promise<{
     handle: FileHandle;

package/dist/observer/pinned-files.js

@@ -5,23 +5,26 @@ import { createHash } from "node:crypto";
 import { constants as fsConstants } from "node:fs";
 import { lstat, open, realpath } from "node:fs/promises";
 import path from "node:path";
-import { readOpenedAtMost } from "../run/contained-output.js";
+import { readOpenedAtMost, readOpenedPrefix } from "../run/contained-output.js";
 import { isPathInside, isSafeRunIdSegment } from "../run/paths.js";
 /**
  * The file's bytes, or null when it cannot be read under the root's checks. With `maxBytes`, a
  * file larger than that is refused from its opened size and the read stops there, so a large file
- * is never held in memory.
+ * is never held in memory. With `length`, only the file's first `length` bytes are read, or all of
+ * a shorter file; with `start` as well, the bytes from `start` to `length`.
  */
 export async function readContainedFile(root, filePathInput, options = {}) {
     const opened = await openContainedFile(root, filePathInput);
     if (!opened)
         return null;
     try {
-        const body = options.maxBytes === undefined
-            ? await opened.handle.readFile()
-            : opened.size > options.maxBytes
-                ? null
-                : await readOpenedAtMost(opened.handle, options.maxBytes);
+        const body = options.length !== undefined
+            ? await readOpenedPrefix(opened.handle, options.length, options.start)
+            : options.maxBytes === undefined
+                ? await opened.handle.readFile()
+                : opened.size > options.maxBytes
+                    ? null
+                    : await readOpenedAtMost(opened.handle, options.maxBytes);
         if (body === null)
             return null;
         // A write that landed during the read changed the file's mtime and ctime.

package/dist/observer/run-routes.d.ts

@@ -17,7 +17,7 @@ export declare function servedRunPaths(runRoot: PinnedDirectory): Promise<Prepar
  * internal: consumed by src/observer/serve.ts. `notesToken` goes into the run's Observer page so
  * it can add notes; a server passes it only for a run it takes notes for.
  */
-export declare function serveRunPath(runRoot: PinnedDirectory, relativePath: string, response: ServerResponse, runtimeStreamUrls?: ObserverRuntimeStreamUrl[], request?: Pick<IncomingMessage, "method" | "headers">, notesToken?: string): Promise<void>;
+export declare function serveRunPath(runRoot: PinnedDirectory, relativePath: string, response: ServerResponse, runtimeStreamUrls?: ObserverRuntimeStreamUrl[], request?: Pick<IncomingMessage, "method" | "headers" | "url">, notesToken?: string): Promise<void>;
 /** internal: exported for the stream lifecycle tests. */
 export declare function withRuntimeStreamUrls(data: ObserverData, runtimeStreamUrls: ObserverRuntimeStreamUrl[]): ObserverData;
 /** internal: consumed by src/observer/serve.ts */

package/dist/observer/run-routes.js

@@ -10,12 +10,13 @@ import { listRuns } from "../run/stored-runs.js";
 import { readAnalysisAccounting } from "../run/costs.js";
 import { bindExistingRunArtifactPaths, isPathInside, isSafeRunIdSegment, } from "../run/paths.js";
 import { isRunOutcome } from "../run/bundle-shape.js";
-import { displayedTraces, loadStreamTraces } from "../run/stream-trace.js";
+import { displayedTraces, loadStreamTraces, } from "../run/stream-trace.js";
 import { isNodeError, isRecord } from "../run/type-guards.js";
 import { MAX_NOTE_FILE_BYTES, readRunNotes, RUN_NOTES_DIR, } from "../run/note-files.js";
 import { analysisCostOf, runCost, runCostLabel } from "../run/run-cost.js";
 import { RUN_STATUS_FILE, RUN_STATUS_STALE_MS, isRunStatusRecord, } from "../run/status.js";
 import { renderObserverHtml } from "./artifact.js";
+import { parseFeedCursors, withFeedCursors } from "./feed-cursors.js";
 import { splitObserverData } from "./participant-items.js";
 import { buildObserverData, observerDataFromSaved, recordedStreamEmbed, withObserverEndings, } from "./data.js";
 import { buildArtifactSecurityHeaders } from "./http.js";
@@ -103,14 +104,14 @@ export async function serveRunPath(runRoot, relativePath, response, runtimeStrea
         return;
     }
     if (cleanedRelativePath === "observer/index.html") {
-        const observerData = await observerDataOrReason(runRoot, runtimeStreamUrls);
-        if ("unavailable" in observerData) {
-            writeResponse(response, 404, `Observer data not found: ${observerData.unavailable}`, "text/plain; charset=utf-8");
+        const observed = await observerDataOrReason(runRoot, runtimeStreamUrls);
+        if ("unavailable" in observed) {
+            writeResponse(response, 404, `Observer data not found: ${observed.unavailable}`, "text/plain; charset=utf-8");
             return;
         }
         const analysis = await readObserverAnalysis(runRoot);
         const notes = await readRunNotes(servedNoteFiles(runRoot));
-        writeResponse(response, 200, renderObserverHtml(observerData, {
+        writeResponse(response, 200, renderObserverHtml(observed.data, {
             analysis,
             notes,
             ...(notesToken === undefined ? {} : { notesToken }),
@@ -121,15 +122,17 @@ export async function serveRunPath(runRoot, relativePath, response, runtimeStrea
     // polls observer-feed.json, the same data with the items, so one projection serves each poll.
     if (cleanedRelativePath === "observer/observer-data.json" ||
         cleanedRelativePath === "observer/observer-feed.json") {
-        const observerData = await observerDataOrReason(runRoot, runtimeStreamUrls);
-        if ("unavailable" in observerData) {
-            writeResponse(response, 404, `Observer data not found: ${observerData.unavailable}`, "text/plain; charset=utf-8");
+        const observed = await observerDataOrReason(runRoot, runtimeStreamUrls, cleanedRelativePath === "observer/observer-feed.json"
+            ? requestedCursors(runRoot, request)
+            : undefined);
+        if ("unavailable" in observed) {
+            writeResponse(response, 404, `Observer data not found: ${observed.unavailable}`, "text/plain; charset=utf-8");
             return;
         }
-        const { shell, items } = splitObserverData(observerData);
+        const { shell, items } = splitObserverData(observed.data);
         writeResponse(response, 200, cleanedRelativePath === "observer/observer-data.json"
             ? JSON.stringify(shell, null, 2)
-            : JSON.stringify({ data: shell, items }), "application/json; charset=utf-8");
+            : JSON.stringify({ data: shell, items: withFeedCursors(items, observed.live) }), "application/json; charset=utf-8");
         return;
     }
     if (cleanedRelativePath === "observer/study-analysis.json") {
@@ -163,18 +166,31 @@ export async function serveRunPath(runRoot, relativePath, response, runtimeStrea
         writeResponse(response, 404, "Not found", "text/plain; charset=utf-8");
     }
 }
+/**
+ * The live cursors a feed poll sends in `after`. A root that checks reads against admitted files
+ * and digests gets none: its digest check covers whole files, and it serves only finished runs.
+ */
+function requestedCursors(runRoot, request) {
+    if (runRoot.admitsFile !== undefined ||
+        runRoot.admitsContent !== undefined ||
+        request?.url === undefined)
+        return undefined;
+    return parseFeedCursors(new URL(request.url, "http://observer.invalid").searchParams.get("after"));
+}
 /** The run's trace files, read through its pinned folder. */
 function pinnedTraceReader(runRoot) {
-    return async (relativePath, maxBytes) => {
+    return async (relativePath, maxBytes, length, start) => {
         const bytes = await readContainedFile(runRoot, path.join(runRoot.physicalPath, relativePath), {
             maxBytes,
+            ...(length === undefined ? {} : { length }),
+            ...(start === undefined ? {} : { start }),
         }).catch(() => null);
         return bytes === null ? { refused: `${relativePath} could not be read` } : { bytes };
     };
 }
 async function readObserverData(runRoot, runtimeStreamUrls = []) {
     const read = await observerDataOrReason(runRoot, runtimeStreamUrls);
-    return "unavailable" in read ? null : read;
+    return "unavailable" in read ? null : read.data;
 }
 /**
  * The run's Observer data, or why there is none. run.json is the source: each trace is loaded
@@ -184,7 +200,7 @@ async function readObserverData(runRoot, runtimeStreamUrls = []) {
  * cannot be read, parsed or used as a bundle (which a browser poll can meet mid-write) gives the
  * reason, a 404 the poller retries, never the saved projection.
  */
-async function observerDataOrReason(runRoot, runtimeStreamUrls) {
+async function observerDataOrReason(runRoot, runtimeStreamUrls, cursors) {
     const record = await readLocalRunStatus(runRoot);
     const runJson = path.join(runRoot.physicalPath, "run.json");
     const bundleBytes = await readContainedFile(runRoot, runJson).catch(() => null);
@@ -193,8 +209,10 @@ async function observerDataOrReason(runRoot, runtimeStreamUrls) {
     // A root admitted for safe serving checks every read against the identity and digest admitted
     // with the run's share_ready verification, so a run.json changed since then is refused, and the
     // saved projection it may serve is the one admitted with the verified run.
-    if (absent || (bundleBytes === null && runRoot.admitsContent !== undefined))
-        return savedObserverData(runRoot, record, runtimeStreamUrls);
+    if (absent || (bundleBytes === null && runRoot.admitsContent !== undefined)) {
+        const saved = await savedObserverData(runRoot, record, runtimeStreamUrls);
+        return "unavailable" in saved ? saved : { data: saved, live: [] };
+    }
     if (bundleBytes === null)
         return { unavailable: "run.json is there but could not be read: it is a link or changed." };
     let stored;
@@ -208,8 +226,12 @@ async function observerDataOrReason(runRoot, runtimeStreamUrls) {
         return { unavailable: "run.json is not a run bundle; it may be mid-write, so try again." };
     }
     try {
-        const bundle = displayedTraces(await loadStreamTraces(pinnedTraceReader(runRoot), stored));
-        return withRuntimeStreamUrls(withLocalRunStatus(record, buildObserverData(bundle, undefined, record), bundle.outcome), runtimeStreamUrls);
+        const loaded = await loadStreamTraces(pinnedTraceReader(runRoot), stored, cursors === undefined ? {} : { liveAfter: (index) => cursors.get(index.path) });
+        const bundle = displayedTraces(loaded);
+        return {
+            data: withRuntimeStreamUrls(withLocalRunStatus(record, buildObserverData(bundle, undefined, record), bundle.outcome), runtimeStreamUrls),
+            live: loaded.live,
+        };
     }
     catch {
         return { unavailable: "run.json could not be shown as a run." };