humanish 0.125.0 → 0.127.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/goal-source.d.ts

@@ -1,5 +1,35 @@
-/** Presentation provenance for computer-use completion; never reclassifies the stored outcome. */
-export type CuaGoalSource = "participant_report" | "condition_matched" | "unavailable";
+/**
+ * The endpoint a computer-use completion came from, as analysis provenance records it
+ * (cuaEndpointSource). Saved analyses hash it, so a new value would make them invalid on read.
+ */
+export declare const CUA_ENDPOINT_SOURCES: readonly ["participant_report", "condition_matched", "unavailable"];
+export type CuaEndpointSource = (typeof CUA_ENDPOINT_SOURCES)[number];
+/**
+ * Presentation provenance for computer-use completion; never reclassifies the stored outcome.
+ * `scheduled_end` and `session_cap` name a session that passed at that clock end without the
+ * participant declaring it reached the goal (ranUntilClockEnd).
+ */
+export type CuaGoalSource = CuaEndpointSource | ClockEnd;
+/** The two clock ends a computer-use session passes at: the stop causes of the same names. */
+export type ClockEnd = "scheduled_end" | "session_cap";
+export declare function isClockEnd(source: CuaGoalSource | undefined): source is ClockEnd;
+/**
+ * The clock end a session ran until, when the participant did not declare that it reached the
+ * goal: its scheduled end or its session cap. Such a session ends as passed, because ending at
+ * the clock is the plan, and its closing report says `DID NOT REACH THE GOAL.` or declares
+ * nothing. The tally and every completion label read this, so none counts it as reaching the
+ * goal. Undefined for every other ending, including a declared `reached` at a clock end.
+ */
+export declare function ranUntilClockEnd(trace: {
+    readonly stopCause?: unknown;
+    readonly declaredOutcome?: unknown;
+}): ClockEnd | undefined;
 export declare function isCuaTrace(value: unknown): boolean;
 export declare function cuaGoalSource(value: unknown, recordedStatus?: unknown): CuaGoalSource | undefined;
+/**
+ * cuaGoalSource for analysis provenance. A clock end reads as it did before it had a source of
+ * its own, so an analysis saved then still matches its run when re-read. The provenance's
+ * `stopCause` and `declaredOutcome` name the clock end.
+ */
+export declare function cuaEndpointSource(value: unknown, recordedStatus?: unknown): CuaEndpointSource | undefined;
 export declare const CUA_COMPLETION_NOTE = "Participant reports alone do not establish task success. A matched stop condition establishes only its declared condition. Run gate and share-safety results are separate.";

package/dist/actors/goal-source.js

@@ -1,3 +1,27 @@
+/**
+ * The endpoint a computer-use completion came from, as analysis provenance records it
+ * (cuaEndpointSource). Saved analyses hash it, so a new value would make them invalid on read.
+ */
+export const CUA_ENDPOINT_SOURCES = [
+    "participant_report",
+    "condition_matched",
+    "unavailable",
+];
+export function isClockEnd(source) {
+    return source === "scheduled_end" || source === "session_cap";
+}
+/**
+ * The clock end a session ran until, when the participant did not declare that it reached the
+ * goal: its scheduled end or its session cap. Such a session ends as passed, because ending at
+ * the clock is the plan, and its closing report says `DID NOT REACH THE GOAL.` or declares
+ * nothing. The tally and every completion label read this, so none counts it as reaching the
+ * goal. Undefined for every other ending, including a declared `reached` at a clock end.
+ */
+export function ranUntilClockEnd(trace) {
+    if (trace.stopCause !== "scheduled_end" && trace.stopCause !== "session_cap")
+        return undefined;
+    return trace.declaredOutcome === "reached" ? undefined : trace.stopCause;
+}
 export function isCuaTrace(value) {
     if (typeof value !== "object" || value === null)
         return false;
@@ -32,7 +56,22 @@ export function cuaGoalSource(value, recordedStatus) {
         (item.title.startsWith("stopWhen matched:") || item.title === "dwell window complete"))) {
         return "condition_matched";
     }
-    // A legacy trace without enough detail cannot establish which endpoint ended the loop.
-    return trace.items.length > 0 ? "participant_report" : "unavailable";
+    return ranUntilClockEnd(trace) ?? endpointOfItems(trace.items);
+}
+// A legacy trace without enough detail cannot establish which endpoint ended the loop.
+function endpointOfItems(items) {
+    return items.length > 0 ? "participant_report" : "unavailable";
+}
+/**
+ * cuaGoalSource for analysis provenance. A clock end reads as it did before it had a source of
+ * its own, so an analysis saved then still matches its run when re-read. The provenance's
+ * `stopCause` and `declaredOutcome` name the clock end.
+ */
+export function cuaEndpointSource(value, recordedStatus) {
+    const source = cuaGoalSource(value, recordedStatus);
+    // cuaGoalSource returns a clock end only after it has checked that `items` is an array.
+    return isClockEnd(source)
+        ? endpointOfItems(value.items)
+        : source;
 }
 export const CUA_COMPLETION_NOTE = "Participant reports alone do not establish task success. A matched stop condition establishes only its declared condition. Run gate and share-safety results are separate.";

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-sources.js

@@ -1,6 +1,6 @@
 import { receivingAnalysisContext } from "../comms/receiving-evidence.js";
 import { eventRecordIdOf, recordIdOf, streamParticipantIdOf } from "../run/participant-records.js";
-import { cuaGoalSource } from "../actors/goal-source.js";
+import { cuaEndpointSource } from "../actors/goal-source.js";
 import { isRecord } from "../run/type-guards.js";
 import { ACTION_CAPTURE_VERSION, } from "./types.js";
 import { decodesToPlainRelativePath, isEvidencePath } from "../run/evidence-files.js";
@@ -82,7 +82,7 @@ export function participantSource(stream, captureVersion) {
             actorStatus: actor?.status ?? null,
             completionReason: actor?.completionReason ?? null,
             stopCause: actor?.stopCause ?? null,
-            goalSource: cuaGoalSource(actor, stream.status) ?? null,
+            goalSource: cuaEndpointSource(actor, stream.status) ?? null,
             declaredOutcome: actor?.declaredOutcome ?? null,
             taskOutcomes: actor?.taskFunnel === undefined
                 ? null

package/dist/analysis/types.d.ts

@@ -1,5 +1,5 @@
 import type { ActorStatus, ActorCompletionReason, ActorStopCause, ParticipantDeclaredOutcome } from "../actors/contract.js";
-import type { CuaGoalSource } from "../actors/goal-source.js";
+import type { CuaEndpointSource } from "../actors/goal-source.js";
 import type { AutomaticAnalysisView } from "./job.js";
 import type { RunAnalysisCost } from "../run/run-cost.js";
 /** Independent interpretation of retained evidence; never a participant or harness verdict. */
@@ -55,7 +55,7 @@ export interface AnalysisParticipantInput {
         actorStatus: ActorStatus | null;
         completionReason: ActorCompletionReason | null;
         stopCause: ActorStopCause | null;
-        goalSource: CuaGoalSource | null;
+        goalSource: CuaEndpointSource | null;
         declaredOutcome: ParticipantDeclaredOutcome | null;
         taskOutcomes: Array<{
             taskId: string;

package/dist/analysis/validation.js

@@ -2,6 +2,7 @@ import { validStoredCodexAnalysisConfig } from "./codex-config.js";
 import { createHash } from "node:crypto";
 import { z } from "zod";
 import { ACTOR_STATUSES, ACTOR_STOP_CAUSES } from "../actors/contract.js";
+import { CUA_ENDPOINT_SOURCES } from "../actors/goal-source.js";
 import { ANALYSIS_LIMITS, EVIDENCE_LIMITS, MAX_ANALYSIS_COHORTS, hasControlCharacter, hasRevisionFields, } from "./analysis-limits.js";
 import { SHA256_HEX_PATTERN, ACTION_CAPTURE_VERSION, ANALYSIS_SCHEMA, ANALYSIS_CORRECTION_SCHEMA, } from "./types.js";
 const text = (max) => z
@@ -178,7 +179,7 @@ const analysisParticipantProvenanceSchema = z
     ])
         .nullable(),
     stopCause: z.enum(ACTOR_STOP_CAUSES).nullable(),
-    goalSource: z.enum(["participant_report", "condition_matched", "unavailable"]).nullable(),
+    goalSource: z.enum(CUA_ENDPOINT_SOURCES).nullable(),
     declaredOutcome: z.enum(["reached", "not_reached", "blocked"]).nullable(),
     taskOutcomes: z
         .array(z

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/observer/data.js

@@ -156,6 +156,13 @@ export function observerDataFromSaved(value) {
         ? null
         : joinObserverData(saved, null);
 }
+const GOAL_SOURCE_LABELS = {
+    participant_report: "Reported complete",
+    condition_matched: "Condition matched",
+    scheduled_end: "Ran until scheduled end",
+    session_cap: "Ran until session cap",
+    unavailable: "Completion source unavailable",
+};
 /** Refresh presentation from recorded actor evidence, including older exported snapshots. */
 export function withObserverEndings(data) {
     const streams = (data.streams ?? []).map(({ ending: _previousEnding, ...stream }) => {
@@ -166,11 +173,7 @@ export function withObserverEndings(data) {
             ...(ending === undefined ? {} : { ending }),
             ...((stream.status === "passed" || stream.status === "complete") && source !== undefined
                 ? {
-                    statusLabel: source === "participant_report"
-                        ? "Reported complete"
-                        : source === "condition_matched"
-                            ? "Condition matched"
-                            : "Completion source unavailable",
+                    statusLabel: GOAL_SOURCE_LABELS[source],
                 }
                 : {}),
             ...(stream.status === "incomplete" || (ending !== undefined && stream.status === "abandoned")

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

@@ -18,11 +18,12 @@ 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. With `length`, only the file's first `length` bytes are read, or all of
- * a shorter file.
+ * 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

@@ -11,7 +11,7 @@ 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. With `length`, only the file's first `length` bytes are read, or all of
- * a shorter file.
+ * 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);
@@ -19,7 +19,7 @@ export async function readContainedFile(root, filePathInput, options = {}) {
         return null;
     try {
         const body = options.length !== undefined
-            ? await readOpenedPrefix(opened.handle, options.length)
+            ? await readOpenedPrefix(opened.handle, options.length, options.start)
             : options.maxBytes === undefined
                 ? await opened.handle.readFile()
                 : opened.size > options.maxBytes

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 */