humanish 0.125.0 → 0.126.0

package/CHANGELOG.md

@@ -8,6 +8,22 @@ The Unreleased section holds the full notes for the next version until it is tag
 
 ## Unreleased
 
+## 0.126.0: Per-participant time zones, session caps and desktop files, page paths, a lighter live Observer (2026-10-13)
+
+humanish 0.126.0 adds per-participant settings for long, mixed studies and a lighter live Observer.
+Each participant can have its own time zone (`participants[].clock`), which now also sets its
+hosted browser, its desktop's panel clock and a `desktop-cli` terminal; an existing
+`actor.clock.timeZone` sets them too. `participants[].maxSessionMs` lets a participant end its
+session sooner and stops one still working at the cap with a closing report.
+`participants[].files` puts files on a participant's desktop for upload dialogs, and each
+computer-use turn records the page it was on (origin and path only). A closing report that opens
+"REACHED THE GOAL." no longer fails its run over the page copy it paraphrases. The served Observer's
+live feed sends only new items each poll: about 90 KB per poll through a synthetic 8-hour,
+24-participant run, where 0.125.0 sent up to 69.5 MB. Offsets and miscased zone names are now
+refused, and so is a zone on the local browser runtime.
+
+[Release notes](https://github.com/danielgwilson/humanish/releases/tag/v0.126.0)
+
 ## 0.125.0: Run bundle v3 with live items in append-only files, loadRunBundle, faster repeated verify (2026-10-12)
 
 humanish 0.125.0 keeps each live flush of a long study small, exports the run bundle loader, and

package/dist/actors/computer-use/actor.d.ts

@@ -78,6 +78,8 @@ export interface CuaActorSessionOptions {
     onMessage?: (text: string) => void;
     /** Runtime-only per-turn raw-frame callback threaded to the loop; see LoopTaps.onScreenshot. */
     onScreenshot?: (frame: Buffer) => void;
+    /** Whether the trace carries the observed page, threaded to the loop; see LoopRunOptions.recordPages. */
+    recordPages?: boolean;
     /** Per-turn trace snapshot callback threaded to the loop; see CuaLoopOptions.onTrace. */
     onTrace?: (items: readonly ActorTraceItem[], usage: ActorTokenUsage, metadata?: CuaLiveMetadata) => void;
 }

package/dist/actors/computer-use/actor.js

@@ -57,6 +57,7 @@ export async function runCuaActorSession(options) {
         ...(options.onMessage === undefined ? {} : { onMessage: options.onMessage }),
         ...(options.onScreenshot === undefined ? {} : { onScreenshot: options.onScreenshot }),
         ...(options.onTrace === undefined ? {} : { onTrace: options.onTrace }),
+        ...(options.recordPages === undefined ? {} : { recordPages: options.recordPages }),
     };
     const result = await runComputerUseLoopWithTaps(loopOptions);
     if (result.trace.executionProfile?.billing === "account-unknown") {

package/dist/actors/computer-use/loop/clock.d.ts

@@ -4,17 +4,18 @@ import type { CuaObservation, ParticipantClock } from "./types.js";
 /**
  * The time text for the request the loop is about to send: the local time when the participant
  * has a time zone, and the end time and the minutes left from the start of its wind-down, or
- * after it tried to end its session before its end (`askedToEnd`). Undefined when there is
- * nothing to say.
+ * after it tried to end its session before its scheduled end (`askedToEnd`). Undefined when
+ * there is nothing to say.
  */
 export declare function clockHint(clock: ParticipantClock | undefined, now: () => number, askedToEnd?: boolean): string | undefined;
 /**
- * Whether the participant has a scheduled end still to come. Its own end before then does not end
- * the session: the end is what the study declared for it.
+ * Whether the participant is held to a scheduled end still to come. Its own end before then does
+ * not end the session: the end is what the study declared for it. A session cap holds no one.
  */
-export declare function beforeScheduledEnd(session: LoopSession): boolean;
+export declare function heldToScheduledEnd(session: LoopSession): boolean;
 /**
- * The stop at the participant's scheduled end, or undefined before it. The session passes as a
- * planned end and the participant is asked for its closing report on the last observation.
+ * The stop at the participant's end, or undefined before it: its scheduled end or its session cap,
+ * which is the stop cause. The session passes as a planned end and the participant is asked for
+ * its closing report on the last observation.
  */
-export declare function scheduledEndStop(session: LoopSession, observation: CuaObservation): Stop | undefined;
+export declare function clockEndStop(session: LoopSession, observation: CuaObservation): Stop | undefined;

package/dist/actors/computer-use/loop/clock.js

@@ -1,13 +1,14 @@
 import { plural } from "../../../run/text.js";
-// What the participant knows about the time. A hosted desktop shows a maximized browser with no
-// OS clock, so a participant told "your shift ends at 11:00" cannot relate it to now unless each
-// turn says so. The text rides the request's context hint, which every provider sends with the
-// turn (OpenAI as a user message, Codex and the local agents as the harness note).
+// What the participant knows about the time. A hosted desktop's panel clock shows the time in the
+// participant's zone, or in UTC without one, and a local browser shows no clock. Neither shows
+// when the session ends, so a participant told "your session ends at 11:00" relates it to now
+// through each turn's text. The text rides the request's context hint, which every provider sends
+// with the turn (OpenAI as a user message, Codex and the local agents as the harness note).
 /**
  * The time text for the request the loop is about to send: the local time when the participant
  * has a time zone, and the end time and the minutes left from the start of its wind-down, or
- * after it tried to end its session before its end (`askedToEnd`). Undefined when there is
- * nothing to say.
+ * after it tried to end its session before its scheduled end (`askedToEnd`). Undefined when
+ * there is nothing to say.
  */
 export function clockHint(clock, now, askedToEnd = false) {
     if (clock === undefined)
@@ -19,31 +20,40 @@ export function clockHint(clock, now, askedToEnd = false) {
     const { end } = clock;
     if (end !== undefined && (askedToEnd || nowMs >= end.atMs - end.windDownMs)) {
         const minutesLeft = Math.max(1, Math.ceil((end.atMs - nowMs) / 60_000));
-        parts.push(`${askedToEnd ? "Your session is not over. " : ""}Your session ends at ${endTime(clock, end.atMs)}, in ${plural(minutesLeft, "minute")}. Keep working until then. The session ends by itself at that time, and you will then be asked for your closing account.`);
+        const at = `${endTime(clock, end.atMs)}${end.kind === "session_cap" ? " at the latest" : ""}`;
+        const close = end.kind === "session_cap"
+            ? "You may end it sooner when you are done. If you are still working then, it ends by itself, and you will then be asked for your closing account."
+            : "Keep working until then. The session ends by itself at that time, and you will then be asked for your closing account.";
+        parts.push(`${askedToEnd ? "Your session is not over. " : ""}Your session ends at ${at}, in ${plural(minutesLeft, "minute")}. ${close}`);
     }
     return parts.length === 0 ? undefined : parts.join(" ");
 }
 /**
- * Whether the participant has a scheduled end still to come. Its own end before then does not end
- * the session: the end is what the study declared for it.
+ * Whether the participant is held to a scheduled end still to come. Its own end before then does
+ * not end the session: the end is what the study declared for it. A session cap holds no one.
  */
-export function beforeScheduledEnd(session) {
+export function heldToScheduledEnd(session) {
     const end = session.settings.clock?.end;
-    return end !== undefined && session.now() < end.atMs;
+    return end !== undefined && end.kind !== "session_cap" && session.now() < end.atMs;
 }
 /**
- * The stop at the participant's scheduled end, or undefined before it. The session passes as a
- * planned end and the participant is asked for its closing report on the last observation.
+ * The stop at the participant's end, or undefined before it: its scheduled end or its session cap,
+ * which is the stop cause. The session passes as a planned end and the participant is asked for
+ * its closing report on the last observation.
  */
-export function scheduledEndStop(session, observation) {
+export function clockEndStop(session, observation) {
     const end = session.settings.clock?.end;
     if (end === undefined || session.now() < end.atMs)
         return undefined;
+    const at = endTime(session.settings.clock, end.atMs);
+    const kind = end.kind ?? "scheduled_end";
     return {
         completionReason: "goal_satisfied",
-        reason: `the participant's scheduled end at ${endTime(session.settings.clock, end.atMs)} was reached`,
-        stopCause: "scheduled_end",
-        debriefTrigger: { kind: "scheduled_end", observation },
+        reason: kind === "session_cap"
+            ? `the participant's session reached its cap at ${at}`
+            : `the participant's scheduled end at ${at} was reached`,
+        stopCause: kind,
+        debriefTrigger: { kind, observation },
     };
 }
 // The end to the nearest minute: a run starts at no particular second, and "ends at 00:09" read

package/dist/actors/computer-use/loop/debrief.d.ts

@@ -1,5 +1,5 @@
 import type { ActorTrace } from "../../contract.js";
-import type { DebriefTrigger } from "./ending.js";
+import { type DebriefTrigger } from "./ending.js";
 import type { LoopSession } from "./session.js";
 import type { CuaTurnRequest } from "./types.js";
 type Debrief = NonNullable<ActorTrace["debrief"]>;

package/dist/actors/computer-use/loop/debrief.js

@@ -1,6 +1,7 @@
 import { closingReportSchema, participantImpressionsSchema } from "../../closing-report.js";
 import { isComputerUseAdmissionLimitError } from "../admission-limit.js";
 import { IMPRESSIONS_ASK, IMPRESSIONS_HINT, recordImpressions } from "./impressions.js";
+import { declaredOutcomeOf } from "./ending.js";
 import { singleDispatch } from "./provider-call.js";
 import { CuaDeadlineError, raceSessionDeadline, requestScope } from "./race.js";
 import { notice } from "./trace.js";
@@ -109,7 +110,7 @@ async function debriefExchange(session, context, trigger, ask, { send, boundMs }
         const turn = provider.requestPolicy === "fail_closed"
             ? await singleDispatch(session, "debrief", (dispatchSignal) => send(request, dispatchSignal), boundMs)
             : await raceSessionDeadline(send(request, scope.signal), boundMs, signal);
-        return acceptDebriefTurn(session, turn, ask, record);
+        return acceptDebriefTurn(session, turn, trigger, ask, record);
     }
     catch (error) {
         // A failed optional report cannot rewrite the already observed structured completion.
@@ -132,7 +133,7 @@ async function debriefExchange(session, context, trigger, ask, { send, boundMs }
         scope.end();
     }
 }
-function acceptDebriefTurn(session, turn, ask, record) {
+function acceptDebriefTurn(session, turn, trigger, ask, record) {
     const { maxUsd, overRunBudget, estimateTurnCostUsd } = session.settings;
     session.usage.record(turn, "debrief");
     session.lastResponseId = turn.responseId ?? session.lastResponseId;
@@ -148,11 +149,18 @@ function acceptDebriefTurn(session, turn, ask, record) {
         return record("failed", "the closing response requested actions or safety checks; none were executed and its report was not accepted", usageReported);
     }
     // First-party providers parse their replies already; these parses cover third-party ports.
-    const { status, detail, ...added } = ask.read(session, turn);
+    const { status, detail, ...added } = ask.read(session, turn, trigger);
     return { ...record(status, detail, usageReported), ...added };
 }
-/** A closing report: its summary and friction as one participant message, then its impressions. */
-function readClosingReport(session, turn) {
+/**
+ * A closing report: its summary and friction as one participant message, then its impressions.
+ * At a scheduled end or a session cap an accepted report is the participant's account of the
+ * session: its summary becomes the session's reason (loopResult), so the outcome it declares
+ * becomes the session's declared outcome. The blocker rule reads a declared `reached` or
+ * `blocked` before the summary's wording. After a matched stop condition or dwell window, the
+ * condition stays the completion evidence.
+ */
+function readClosingReport(session, turn, trigger) {
     const closing = closingReportSchema.safeParse(turn.closingReport);
     if (!closing.success) {
         return {
@@ -173,6 +181,8 @@ function readClosingReport(session, turn) {
     }));
     session.trace.bump("messages");
     session.impressions = recordImpressions(session, closing.data.impressions);
+    if (trigger.kind === "scheduled_end" || trigger.kind === "session_cap")
+        session.declaredOutcome = declaredOutcomeOf(turn, closing.data.summary);
     return {
         status: "completed",
         detail: "one read-only report; no additional desktop actions; original stop and task outcomes preserved",

package/dist/actors/computer-use/loop/ending.d.ts

@@ -8,7 +8,7 @@ import type { CuaObservation, CuaProvider, CuaTurn } from "./types.js";
  * the participant's own ending when only its impressions are missing.
  */
 export interface DebriefTrigger {
-    readonly kind: "stop_when" | "dwell" | "scheduled_end" | "participant_end";
+    readonly kind: "stop_when" | "dwell" | "scheduled_end" | "session_cap" | "participant_end";
     /** The final observation, already captured; the debrief request sends it without observing. */
     readonly observation: CuaObservation;
 }
@@ -22,12 +22,15 @@ export interface Stop {
 }
 /**
  * Read the fixed closing line the prompt asks for: the first non-empty line of the
- * participant's last message, exactly one of three phrases, punctuation and case forgiven. Anything
- * else is absence, never a guess. Exported for tests.
+ * participant's last message or closing report summary, exactly one of three phrases,
+ * punctuation and case forgiven. Anything else is absence, never a guess. Exported for tests.
  */
 export declare function declaredOutcomeFromClosingLine(message: string | undefined): ParticipantDeclaredOutcome | undefined;
-/** The participant's own word for how it ended: a schema field first, then the closing line. */
-export declare function declaredOutcomeOf(turn: CuaTurn): ParticipantDeclaredOutcome | undefined;
+/**
+ * The participant's own word for how it ended: the turn's schema field first, then the closing
+ * line of `text`, its last message or its closing report's summary.
+ */
+export declare function declaredOutcomeOf(turn: CuaTurn, text: string | undefined): ParticipantDeclaredOutcome | undefined;
 /**
  * The participant reported a natural endpoint. "not_reached" is a participant who stopped without
  * finishing: gave_up, which tallies as abandoned. "blocked" keeps goal_satisfied here (the actor

package/dist/actors/computer-use/loop/ending.js

@@ -6,8 +6,8 @@ import { notice } from "./trace.js";
 import { plural } from "../../../run/text.js";
 /**
  * Read the fixed closing line the prompt asks for: the first non-empty line of the
- * participant's last message, exactly one of three phrases, punctuation and case forgiven. Anything
- * else is absence, never a guess. Exported for tests.
+ * participant's last message or closing report summary, exactly one of three phrases,
+ * punctuation and case forgiven. Anything else is absence, never a guess. Exported for tests.
  */
 export function declaredOutcomeFromClosingLine(message) {
     if (message === undefined)
@@ -27,9 +27,12 @@ export function declaredOutcomeFromClosingLine(message) {
         return "blocked";
     return undefined;
 }
-/** The participant's own word for how it ended: a schema field first, then the closing line. */
-export function declaredOutcomeOf(turn) {
-    return turn.outcome ?? declaredOutcomeFromClosingLine(turn.message);
+/**
+ * The participant's own word for how it ended: the turn's schema field first, then the closing
+ * line of `text`, its last message or its closing report's summary.
+ */
+export function declaredOutcomeOf(turn, text) {
+    return turn.outcome ?? declaredOutcomeFromClosingLine(text);
 }
 /**
  * The participant reported a natural endpoint. "not_reached" is a participant who stopped without

package/dist/actors/computer-use/loop/observation.d.ts

@@ -43,7 +43,13 @@ export declare class DesktopObserver {
      * session is already over.
      */
     observeFinalTasks(turnNumber: number): Promise<void>;
+    /**
+     * Observe the desktop and note the observation's page as the session's final page. Every
+     * observation passes through here, so the page recordScreenshot puts on an item is the page of
+     * the observation it records.
+     */
     private observeBounded;
+    private observeOrRetry;
     /**
      * The observation with every utterance heard since the provider last saw one. New utterances are
      * recorded as notices; too many pending utterances fail the executor as invalid_response.

package/dist/actors/computer-use/loop/observation.js

@@ -1,6 +1,7 @@
 import { evaluateStopWhen } from "../../stop-conditions.js";
 import { ComputerUseExecutorError, isComputerUseExecutorError } from "../executor-error.js";
 import { CUA_SPEECH_LIMITS } from "../speech.js";
+import { tracePage } from "../../../evidence/trace-page.js";
 import { dwellCompleted, missingFrame, stopWhenMatched } from "./ending.js";
 import { CuaAbortError, CuaStallError, raceCallBound } from "./race.js";
 import { notice } from "./trace.js";
@@ -119,10 +120,24 @@ export class DesktopObserver {
                 throw error;
         }
     }
+    /**
+     * Observe the desktop and note the observation's page as the session's final page. Every
+     * observation passes through here, so the page recordScreenshot puts on an item is the page of
+     * the observation it records.
+     */
+    async observeBounded(label) {
+        const observation = await this.observeOrRetry(label);
+        const { session } = this;
+        session.finalPage =
+            session.settings.recordPages === false
+                ? undefined
+                : tracePage(observation.url, (text) => session.redactNarration(text));
+        return observation;
+    }
     // An executor without stallRecovery "fail_closed" gets one retry of a stalled observe.
     // One that cannot safely replay a pending request opts out, so even a shorter outer bound stops
     // without retrying.
-    async observeBounded(label) {
+    async observeOrRetry(label) {
         const { session } = this;
         const { executor } = session;
         try {
@@ -179,10 +194,13 @@ export class DesktopObserver {
         const path = await session.writeScreenshot(`${label}.png`, bytes);
         const screenshotRef = { path, redaction: method };
         session.lastScreenshotRef = screenshotRef;
+        const page = session.finalPage;
         session.trace.record("screenshot", () => ({
             lifecycle: "completed",
             title: label,
             screenshotRef,
+            // A copy: the live flush freezes a recorded item, and finalPage stays the session's own.
+            ...(page === undefined ? {} : { page: { ...page } }),
         }));
         session.trace.bump("screenshots");
     }

package/dist/actors/computer-use/loop/session.d.ts

@@ -1,4 +1,4 @@
-import type { ActorTraceItem, ParticipantDeclaredOutcome, ParticipantImpressions } from "../../contract.js";
+import type { ActorTraceItem, ParticipantDeclaredOutcome, ParticipantImpressions, TracePage } from "../../contract.js";
 import type { AffordanceObservation } from "../../affordance.js";
 import { TaskTracker } from "../../../study/tasks.js";
 import type { DebriefTrigger, Stop } from "./ending.js";
@@ -12,7 +12,7 @@ export type ScreenshotRef = NonNullable<ActorTraceItem["screenshotRef"]>;
  * wrapped callbacks are fields on LoopSession instead. Callers destructure hooks to call them.
  */
 export type LoopSettings = {
-    readonly [K in "instructions" | "persona" | "redaction" | "stopWhen" | "dwell" | "clock" | "tasks" | "maxUsd" | "overRunBudget" | "estimateTurnCostUsd" | "onObservedUrl" | "onMessage" | "onScreenshot" | "onTrace"]: LoopRunOptions[K];
+    readonly [K in "instructions" | "persona" | "redaction" | "stopWhen" | "dwell" | "clock" | "tasks" | "maxUsd" | "overRunBudget" | "estimateTurnCostUsd" | "onObservedUrl" | "onMessage" | "onScreenshot" | "onTrace" | "recordPages"]: LoopRunOptions[K];
 };
 /** The participant's dispatched actions, as the backstop and failure notices describe them. */
 export interface ActionHistory {
@@ -61,6 +61,8 @@ export declare class LoopSession {
     lastScreenshotRef: ScreenshotRef | undefined;
     lastResponseId: string | undefined;
     observedAppState: boolean;
+    /** The page of the session's last observation; undefined when that observation read no URL. */
+    finalPage: TracePage | undefined;
     declaredOutcome: ParticipantDeclaredOutcome | undefined;
     /** Set by a structured stop; the debrief follows it even if the session then failed. */
     debriefTrigger: DebriefTrigger | undefined;

package/dist/actors/computer-use/loop/session.js

@@ -61,6 +61,8 @@ export class LoopSession {
     // Whether any observation carried appState. trace.ts states it in redaction.notes; the appState
     // itself is never persisted.
     observedAppState = false;
+    /** The page of the session's last observation; undefined when that observation read no URL. */
+    finalPage;
     declaredOutcome;
     /** Set by a structured stop; the debrief follows it even if the session then failed. */
     debriefTrigger;
@@ -70,7 +72,7 @@ export class LoopSession {
     scrubText;
     constructor(options) {
         // Read once, in this order: a caller mutating its options object mid-run changes nothing.
-        const { instructions, provider, executor, persona, redaction, timeoutMs, now, signal, idleSteps = DEFAULT_IDLE_STEPS, noProgressSteps = DEFAULT_NO_PROGRESS_STEPS, maxWaitMs, idleWaitMs, acknowledgeSafetyChecks = () => null, redactScreenshots = false, scrubText = (text) => text, writeScreenshot = async (name) => `screenshots/${name}`, stopWhen, dwell, clock, sleep = (ms) => new Promise((resolve) => setTimeout(resolve, ms)), tasks, maxUsd, overRunBudget, estimateTurnCostUsd, requireReportedUsageForSpendCap = false, onObservedUrl, onMessage, onScreenshot, onTrace, } = options;
+        const { instructions, provider, executor, persona, redaction, timeoutMs, now, signal, idleSteps = DEFAULT_IDLE_STEPS, noProgressSteps = DEFAULT_NO_PROGRESS_STEPS, maxWaitMs, idleWaitMs, acknowledgeSafetyChecks = () => null, redactScreenshots = false, scrubText = (text) => text, writeScreenshot = async (name) => `screenshots/${name}`, stopWhen, dwell, clock, sleep = (ms) => new Promise((resolve) => setTimeout(resolve, ms)), tasks, maxUsd, overRunBudget, estimateTurnCostUsd, requireReportedUsageForSpendCap = false, onObservedUrl, onMessage, onScreenshot, onTrace, recordPages, } = options;
         this.settings = {
             instructions,
             persona,
@@ -86,6 +88,7 @@ export class LoopSession {
             onMessage,
             onScreenshot,
             onTrace,
+            recordPages,
         };
         this.provider = provider;
         this.executor = executor;

package/dist/actors/computer-use/loop/trace.js

@@ -67,8 +67,9 @@ export function loopResult(session, stop, debrief) {
     const { provider, settings, trace: recorder, usage } = session;
     const { completionReason, stopCause } = stop;
     // A participant whose session ended on the clock has its closing account as its reason, as one
-    // that ended the session itself has its last message; the stop cause keeps the scheduled end.
-    const reason = stopCause === "scheduled_end" && debrief?.report !== undefined
+    // that ended the session itself has its last message; the stop cause keeps the scheduled end or
+    // the session cap.
+    const reason = (stopCause === "scheduled_end" || stopCause === "session_cap") && debrief?.report !== undefined
         ? debrief.report.summary
         : stop.reason;
     const completedAtMs = session.now();
@@ -131,6 +132,7 @@ export function loopResult(session, stop, debrief) {
         waitSettings: { ...session.waits },
         counts,
         items: recorder.items,
+        ...(session.finalPage === undefined ? {} : { finalPage: session.finalPage }),
         ...(session.actionHistory.affordances.length > 0
             ? { affordanceUse: summarizeAffordanceUse(session.actionHistory.affordances) }
             : {}),

package/dist/actors/computer-use/loop/types.d.ts

@@ -4,12 +4,18 @@ import type { RedactionHooks } from "../../../evidence/redaction.js";
 import type { DwellWindow, StopWhen } from "../../stop-conditions.js";
 import type { StudyTask } from "../../../study/tasks.js";
 import type { ReasoningEffort } from "../../reasoning-effort.js";
-/** The participant's clock: its local time zone and its scheduled end, on the loop's clock. */
+/** The participant's clock: its local time zone and its end, on the loop's clock. */
 export interface ParticipantClock {
     readonly timeZone?: string;
+    /**
+     * When the session ends. `kind` is `scheduled_end` when absent: the participant is held to the
+     * end and may not end its session before it. A `session_cap` is the latest the session lasts:
+     * the participant may end it sooner.
+     */
     readonly end?: {
         readonly atMs: number;
         readonly windDownMs: number;
+        readonly kind?: "scheduled_end" | "session_cap";
     };
 }
 /**
@@ -94,9 +100,10 @@ export interface CuaObservation {
     appState?: Record<string, unknown>;
     /**
      * Optional browser state captured by an executor that can inspect the driven browser
-     * deterministically (for example via Chrome DevTools Protocol). These fields are runtime-only:
-     * they may drive stopWhen and progress decisions, but the loop never persists raw URL/title/text
-     * into the trace. Persisting arbitrary DOM text would make private-data leakage too easy.
+     * deterministically (for example via Chrome DevTools Protocol). These fields drive stopWhen and
+     * progress decisions. The loop never persists the raw URL, title or text: persisting arbitrary
+     * DOM text would make private-data leakage too easy. From the URL it records only the page's
+     * origin and redacted path (`page` on screenshot items, `finalPage`; src/evidence/trace-page.ts).
      */
     url?: string;
     /**
@@ -359,7 +366,7 @@ export interface CuaLoopOptions {
      * name, every request carries the local time. With `end`, from `end.atMs - end.windDownMs`
      * every request names the end time (in `timeZone`, else UTC) and the minutes left, and at
      * `end.atMs`, read on `now`, the loop asks for the closing report and ends the session with
-     * stop cause `scheduled_end`.
+     * stop cause `end.kind` (`scheduled_end` when absent).
      */
     clock?: ParticipantClock;
     /**
@@ -421,7 +428,7 @@ export interface LoopTaps {
     /**
      * Runtime-only URL tap: called with `observation.url` for each observation a turn may receive
      * (the initial one, each post-action one and the one after a dwell window). The loop never
-     * persists the URL. Default: no-op.
+     * persists the raw URL. Default: no-op.
      *
      * Built-in caller: the external-public shared-world handoff (src/routes/shared-world/handoff.ts)
      * latches the host participant's lobby URL and checks that each follower reached the same lobby.
@@ -447,8 +454,15 @@ export interface LoopTaps {
      */
     onScreenshot?: (frame: Buffer) => void;
 }
-/** The loop's options inside humanish: the public ones plus the handoff's taps. */
-export type LoopRunOptions = CuaLoopOptions & LoopTaps;
+/** The loop's options inside humanish: the public ones, the handoff's taps and the page switch. */
+export type LoopRunOptions = CuaLoopOptions & LoopTaps & {
+    /**
+     * Whether screenshot items and the trace carry the observed page (`page`, `finalPage`).
+     * Default true. The shared-world route passes false: its observed URLs land in the bundle only
+     * as digests (docs/architecture/external-public-shared-world.md).
+     */
+    recordPages?: boolean;
+};
 export type CuaLiveMetadata = Pick<ActorTrace, "executionProfile" | "providerRequests" | "historyTurnsOmitted">;
 /** What runComputerUseLoop returns; the public name for an actor session result. */
 export type CuaLoopResult = ActorSessionResult;

package/dist/actors/computer-use/loop.js

@@ -2,7 +2,7 @@ import { closingReportSchema } from "../closing-report.js";
 import { ComputerUseProviderError } from "./provider-error.js";
 import { runActionBatch } from "./loop/actions.js";
 import { advanceBackstop, startBackstop, } from "./loop/backstop.js";
-import { beforeScheduledEnd, clockHint, scheduledEndStop } from "./loop/clock.js";
+import { clockEndStop, clockHint, heldToScheduledEnd } from "./loop/clock.js";
 import { requestDebrief } from "./loop/debrief.js";
 import * as stops from "./loop/ending.js";
 import { declaredOutcomeOf } from "./loop/ending.js";
@@ -118,7 +118,7 @@ async function runTurns(session, conversation) {
         const blocked = reviewSafetyChecks(session, conversation, turn);
         if (blocked !== undefined)
             return blocked;
-        if ((turn.done || turn.actions.length === 0) && beforeScheduledEnd(session)) {
+        if ((turn.done || turn.actions.length === 0) && heldToScheduledEnd(session)) {
             const held = keepWorking(session, conversation, backstop, observation);
             if ("stop" in held)
                 return held.stop;
@@ -127,7 +127,7 @@ async function runTurns(session, conversation) {
         }
         if (turn.done || turn.actions.length === 0) {
             // The declared outcome is kept even if redacting the participant's summary fails.
-            session.declaredOutcome = declaredOutcomeOf(turn);
+            session.declaredOutcome = declaredOutcomeOf(turn, turn.message);
             const ended = stops.participantEnded(turn, session.declaredOutcome, (text) => session.redactNarration(text));
             const report = closingReportSchema.safeParse(turn.closingReport).data;
             // A provider that can ask for impressions alone does so after the session, like a debrief.
@@ -152,7 +152,7 @@ async function runTurns(session, conversation) {
             actions: turn.actions,
             observation,
             heardNewSpeech: observer.heardNewSpeech,
-            waitingIsTheTask: beforeScheduledEnd(session),
+            waitingIsTheTask: heldToScheduledEnd(session),
         }, { idleSteps: session.idleSteps, noProgressSteps: session.noProgressSteps });
         backstop = step.backstop;
         const stalled = applyBackstop(session, conversation, step, [checkpoint.hint, batch.hint]);
@@ -204,7 +204,7 @@ function refuseAccountBilledCaps(options) {
 function haltBeforeTurn(session, observation) {
     if (session.signal?.aborted)
         return stops.harnessAborted;
-    return (scheduledEndStop(session, observation) ??
+    return (clockEndStop(session, observation) ??
         (session.remaining() < 0 ? stops.timeLimit(session) : undefined));
 }
 /**

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