humanish 0.124.0 → 0.126.0

package/CHANGELOG.md

@@ -8,6 +8,37 @@ 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
+verifies a finished study faster. Run bundles are now `humanish.run-bundle.v3`: a running
+participant's items so far live in an append-only file under `live/`, and each flush appends only
+the items recorded since the last one. On a synthetic run of 24 participants working 8 hours, a
+flush wrote about 0.23 MB in about 0.24 s, where 0.124.0 wrote up to 120 MB in 3.0 s. A finished
+v3 bundle differs from v2 only in its schema name; 0.124.0 and earlier refuse it by name.
+`loadRunBundle(cwd, run)` returns run.json with every trace and live file joined and checked, for
+v1, v2 and v3 bundles. The five verifies of a finished study read each screenshot once: 10 s in
+all for 1,203 screenshots, down from 35 s. A key in a study's title is redacted from the bundle,
+and one in a persona id or desktop template fails at parse instead of blocking the run.
+
+[Release notes](https://github.com/danielgwilson/humanish/releases/tag/v0.125.0)
+
 ## 0.124.0: Small Observer files for long studies, faster verify, closing reports under zero data retention (2026-10-12)
 
 humanish 0.124.0 keeps a long study's Observer files small, checks screenshots about eight times

package/CONTEXT.md

@@ -12,7 +12,7 @@ bundle and output fields keep older spellings; the second table maps them.
 | Term                | Meaning                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                               | Where it lives in the code                                                                                                                                                                                                                                                                                                                                                                                  |
 | ------------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | ----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
 | study               | What a user designs and runs: one YAML file that declares the subject, the actor, the participants and the caps. The file lives at `humanish/studies/<id>.yaml` with schema `humanish.study.v3`, read by `humanish study` and `--study`. humanish refuses a 0.107 `humanish.lab.v2` file, and `humanish migrate` converts it (second table).                                                                                                                                                                                          | `src/study/`; `StudyConfig` in `src/study/types.ts`, parsed by `parseStudy` in `src/study/config.ts`                                                                                                                                                                                                                                                                                                        |
-| run                 | One execution of a study, on disk: `.humanish/runs/<runId>/`, with `run.json` (`humanish.run-bundle.v2`) as the source of truth and each participant's trace in its own file.                                                                                                                                                                                                                                                                                                                                                         | `src/run/`; `RunBundle` in `src/run/bundle.ts`                                                                                                                                                                                                                                                                                                                                                              |
+| run                 | One execution of a study, on disk: `.humanish/runs/<runId>/`, with `run.json` (`humanish.run-bundle.v3`) as the source of truth and each participant's trace in its own file.                                                                                                                                                                                                                                                                                                                                                         | `src/run/`; `RunBundle` in `src/run/bundle.ts`                                                                                                                                                                                                                                                                                                                                                              |
 | dry run             | A run with no live participant, from `--dry-run` or `mode: dry-run`. humanish writes a synthetic run bundle, review and Observer with no browser, model, keys or provider spend, and tests no product behavior. The `preview` route only dry-runs; "preview" names that route and nothing else.                                                                                                                                                                                                                                       | `runDryRun` in `src/run/dry-run.ts`; `resolveStudyDryRun` in `src/study/plan.ts`                                                                                                                                                                                                                                                                                                                            |
 | participant         | One simulated person, or agent, taking part in a study. The planner builds each one's record (id, persona id, assignment, labels and the route's own fields). Shared-world participants resolve the plan's records; computer-use participants rebuild the same records from the study config with `computerUseParticipants` (`src/study/plan-participants.ts`) and resolve those. `ResolvedParticipant` adds the bundle ids, persona and prompt. `run.json` records each one as a `simulations[]` entry with one or more `streams[]`. | `ResolvedParticipant` in `src/run/participant.ts`; the planned records in `src/study/plan-participants.ts`. Computer-use and shared-world participants run a `DesktopParticipantRun` (`src/routes/computer-use/types.ts`). The terminal session (`src/routes/terminal/session.ts`), scripted surfaces (`src/routes/scripted/plan.ts`) and fixture simulations (`src/run/dry-run.ts`) still build their own. |
 | persona             | Who a participant is: traits, background, device. `humanish/personas/<id>.yaml`.                                                                                                                                                                                                                                                                                                                                                                                                                                                      | `src/study/persona.ts`, `src/study/persona-resolve.ts`                                                                                                                                                                                                                                                                                                                                                      |

package/README.md

@@ -335,7 +335,7 @@ and the library exports.
 - Breaking changes ship together in one minor release. Its release notes carry a migration
   table: each old form, its new form, and the change to make.
 - The study file and the run bundle carry versioned schemas, `humanish.study.v3` and
-  `humanish.run-bundle.v2`. A breaking change to either one bumps its version.
+  `humanish.run-bundle.v3`. A breaking change to either one bumps its version.
 
 Pin the exact version in `package.json` and read [CHANGELOG.md](CHANGELOG.md) before upgrading.
 
@@ -483,7 +483,7 @@ for the supported library seam.
 
 - run a study: `runStudy`, `RunStudyOptions`, `StudyOutcome`, `StudyResult`, `StudyEvent`, `routeOf`,
   `parseStudy`, `STUDY_SCHEMA`;
-- read a run: `verifyRun`, `renderObserver`, `RunBundle`, `ActorTrace`;
+- read a run: `verifyRun`, `loadRunBundle`, `renderObserver`, `RunBundle`, `ActorTrace`;
 - bring a participant: `ComputerUseProvider`, `ComputerUseExecutor`, `ProviderContext`,
   `createOpenAiResponsesProvider`, `runComputerUseLoop`, `defaultRedactionHooks`;
 - score a run: `AdapterScorerModule` and its scoring contexts.

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));
 }
 /**