humanish 0.125.0 → 0.127.0

package/dist/substrates/e2b/desktop-clock.js

@@ -0,0 +1,29 @@
+// The clock in the hosted desktop's panel. The stock template's XFCE panel sits above every window,
+// so a participant sees its clock in each screenshot, and it shows the desktop's zone, UTC, unless
+// its clock plugin names another.
+import { shellQuote } from "../shell.js";
+import { e2bShell } from "./shell.js";
+/**
+ * Set every clock in the desktop's XFCE panel to `timeZone`, a tz database name, by writing the
+ * clock plugin's `timezone` property through xfconf-query. The property lives in the session's
+ * settings daemon, reached over the session bus whose address xfce4-session holds, and the panel
+ * redraws its clock when the property changes (live: 02:12 UTC became 11:12 for Asia/Tokyo with no
+ * restart). A desktop without xfconf-query or without a clock plugin is left as it is. Throws with
+ * xfconf-query's error output when a clock is found and cannot be set.
+ */
+export async function setPanelClockZone(desktop, timeZone, requestTimeoutMs) {
+    const result = await e2bShell(desktop).run([
+        `zone=${shellQuote(timeZone)}`,
+        "command -v xfconf-query >/dev/null 2>&1 || exit 0",
+        'session_pid="$(pgrep -x xfce4-session | head -n 1)"',
+        'if [ -n "$session_pid" ]; then',
+        `  bus="$(tr '\\0' '\\n' < "/proc/$session_pid/environ" | sed -n 's/^DBUS_SESSION_BUS_ADDRESS=//p')"`,
+        '  if [ -n "$bus" ]; then export DBUS_SESSION_BUS_ADDRESS="$bus"; fi',
+        "fi",
+        `for plugin in $(xfconf-query -c xfce4-panel -p /plugins -l -v | awk '$2 == "clock" { print $1 }'); do`,
+        '  xfconf-query -c xfce4-panel -p "$plugin/timezone" -n -t string -s "$zone" || exit 1',
+        "done",
+    ].join("\n"), { requestTimeoutMs, timeoutMs: 15_000 });
+    if (result.exitCode !== 0)
+        throw new Error(result.stderr.trim() || `xfconf-query exited ${result.exitCode}`);
+}

package/dist/substrates/e2b/lifetime.d.ts

@@ -45,14 +45,24 @@ export type ConcurrentSandboxes = {
 export declare function concurrentSandboxes(env: Readonly<Record<string, string | undefined>>): ConcurrentSandboxes;
 /** The limit in use and where it came from, or why the setting cannot be read (doctor's row). */
 export declare function describeConcurrentSandboxes(limit: ConcurrentSandboxes): string;
+/** The setting that lowers how many participants a study runs at once, on any desktop. */
+export declare const CUA_MAX_CONCURRENCY_ENV = "HUMANISH_CUA_MAX_CONCURRENCY";
 /**
- * How many participants a hosted study runs at once: its `concurrency` (the declared
- * execution.concurrency clamped to the roster, else every participant), lowered to what the plan
- * runs. `declared` says whether the study set it. `alongside` counts the sandboxes the study keeps
- * for the whole run besides its participants' desktops, such as a shared world's app, and
- * `minimum` is the fewest at once the route can run. A declared value that does not fit is a
- * refusal naming the setting value that admits it. `lowered` is the warning a plan records when
- * the limit holds an undeclared default to waves.
+ * HUMANISH_CUA_MAX_CONCURRENCY when it is a whole number of 1 or more, else undefined: the
+ * operator's own bound on participants at once on this machine, which may only lower a study's.
+ * Any other value is ignored.
+ */
+export declare function concurrencyCap(env: Readonly<Record<string, string | undefined>>): number | undefined;
+/**
+ * How many participants a study runs at once: its `concurrency` (the declared
+ * execution.concurrency clamped to the roster, else every participant), lowered to `cap`
+ * (concurrencyCap) and then to what the E2B plan runs (`sandboxes`, on a hosted desktop).
+ * `declared` says whether the study set it. `alongside` counts the sandboxes the study keeps for
+ * the whole run besides its participants' desktops, such as a shared world's app, and `minimum` is
+ * the fewest at once the route can run. A declared value the E2B plan cannot run, or a cap under
+ * `minimum`, is a refusal naming the setting. `lowered` is the warning a plan records when the cap
+ * or the E2B limit lowers the count; when both do, it is the E2B limit's, since that sets the
+ * count. `loweredFrom` is the count the cap lowered, when the cap sets the count.
  */
 export declare function participantsAtOnce(study: {
     readonly concurrency: number;
@@ -60,10 +70,14 @@ export declare function participantsAtOnce(study: {
     readonly participants: number;
     readonly alongside?: number;
     readonly minimum?: number;
-}, limit: ConcurrentSandboxes): {
+}, limits: {
+    readonly sandboxes?: ConcurrentSandboxes;
+    readonly cap?: number | undefined;
+}): {
     readonly ok: true;
     readonly count: number;
     readonly lowered?: string;
+    readonly loweredFrom?: number;
 } | {
     readonly ok: false;
     readonly message: string;

package/dist/substrates/e2b/lifetime.js

@@ -1,5 +1,6 @@
 // The operator's E2B plan limits humanish plans against: how long a sandbox may live and how many
-// run at once. Also the budgets the desktop routes add to a participant's own deadline when they set
+// run at once, with the operator's own bound on participants at once (HUMANISH_CUA_MAX_CONCURRENCY).
+// Also the budgets the desktop routes add to a participant's own deadline when they set
 // a sandbox's server-side timeout. A dead host process can never orphan a sandbox past that
 // timeout, so every route derives it from these values.
 import { plural } from "../../run/text.js";
@@ -88,19 +89,62 @@ export function describeConcurrentSandboxes(limit) {
     if (!limit.ok)
         return limit.message;
     return limit.source === "setting"
-        ? `${limit.count} at once, from ${CONCURRENCY_SETTING}. A study that runs more desktops at once runs them in waves, and an execution.concurrency above it is refused before any sandbox is created.`
+        ? `${limit.count} at once, from ${CONCURRENCY_SETTING}. A study that runs more desktops at once runs them in waves, and an execution.concurrency above it is refused before any sandbox is created, unless ${CUA_MAX_CONCURRENCY_ENV} lowers it to the limit or below.`
         : `${limit.count} at once, E2B's Hobby limit. On a plan that runs more (Pro runs ${PRO_CONCURRENT_SANDBOXES}), set ${CONCURRENCY_SETTING} to that plan's limit.`;
 }
+/** The setting that lowers how many participants a study runs at once, on any desktop. */
+export const CUA_MAX_CONCURRENCY_ENV = "HUMANISH_CUA_MAX_CONCURRENCY";
 /**
- * How many participants a hosted study runs at once: its `concurrency` (the declared
- * execution.concurrency clamped to the roster, else every participant), lowered to what the plan
- * runs. `declared` says whether the study set it. `alongside` counts the sandboxes the study keeps
- * for the whole run besides its participants' desktops, such as a shared world's app, and
- * `minimum` is the fewest at once the route can run. A declared value that does not fit is a
- * refusal naming the setting value that admits it. `lowered` is the warning a plan records when
- * the limit holds an undeclared default to waves.
+ * HUMANISH_CUA_MAX_CONCURRENCY when it is a whole number of 1 or more, else undefined: the
+ * operator's own bound on participants at once on this machine, which may only lower a study's.
+ * Any other value is ignored.
  */
-export function participantsAtOnce(study, limit) {
+export function concurrencyCap(env) {
+    const cap = readPositiveInt(env[CUA_MAX_CONCURRENCY_ENV], 0);
+    return cap > 0 ? cap : undefined;
+}
+/**
+ * How many participants a study runs at once: its `concurrency` (the declared
+ * execution.concurrency clamped to the roster, else every participant), lowered to `cap`
+ * (concurrencyCap) and then to what the E2B plan runs (`sandboxes`, on a hosted desktop).
+ * `declared` says whether the study set it. `alongside` counts the sandboxes the study keeps for
+ * the whole run besides its participants' desktops, such as a shared world's app, and `minimum` is
+ * the fewest at once the route can run. A declared value the E2B plan cannot run, or a cap under
+ * `minimum`, is a refusal naming the setting. `lowered` is the warning a plan records when the cap
+ * or the E2B limit lowers the count; when both do, it is the E2B limit's, since that sets the
+ * count. `loweredFrom` is the count the cap lowered, when the cap sets the count.
+ */
+export function participantsAtOnce(study, limits) {
+    const capped = cappedAtOnce(study, limits.cap);
+    if (!capped.ok || limits.sandboxes === undefined)
+        return capped;
+    // A count the cap lowered is the operator's bound and no longer the study's declared value, so
+    // the E2B limit runs it in waves as it would an undeclared default.
+    const left = capped.loweredFrom === undefined
+        ? study
+        : { ...study, concurrency: capped.count, declared: false };
+    const planned = sandboxesAtOnce(left, limits.sandboxes);
+    return !planned.ok || planned.count < capped.count ? planned : capped;
+}
+/** participantsAtOnce under the cap alone. */
+function cappedAtOnce(study, cap) {
+    if (cap === undefined || cap >= study.concurrency)
+        return { ok: true, count: study.concurrency };
+    const minimum = study.minimum ?? 1;
+    if (cap < minimum)
+        return {
+            ok: false,
+            message: `This study runs at least ${minimum} participants at once, and ${CUA_MAX_CONCURRENCY_ENV} allows ${cap}. Set it to ${minimum} or more, or unset it.`,
+        };
+    return {
+        ok: true,
+        count: cap,
+        loweredFrom: study.concurrency,
+        lowered: `This study's ${study.participants} participants run ${cap} at a time, because ${CUA_MAX_CONCURRENCY_ENV} is ${cap}.`,
+    };
+}
+/** participantsAtOnce under the E2B plan's limit alone. */
+function sandboxesAtOnce(study, limit) {
     if (!limit.ok)
         return limit;
     const alongside = study.alongside ?? 0;

package/dist/substrates/e2b/sdk.d.ts

@@ -154,6 +154,12 @@ export interface E2BDesktopSandbox {
             requestTimeoutMs?: number;
             useOctetStream?: boolean;
         }): Promise<unknown>;
+        /** A file's size as the sandbox sees it. A relative path is under the sandbox user's home. */
+        getInfo?(path: string, options?: {
+            requestTimeoutMs?: number;
+        }): Promise<{
+            size: number;
+        }>;
     };
     launch(application: string, uri?: string): Promise<void>;
     /** Open a file or URL with the desktop's default application (present on @e2b/desktop >= 1.x). */

package/dist/verify/pages.d.ts

@@ -0,0 +1,7 @@
+import type { RunBundle } from "../run/bundle.js";
+/**
+ * One finding per recorded page that holds more than an origin and a path, in each finished
+ * trace's items and summary and each running participant's items. A finding names where the page
+ * is, never what it says.
+ */
+export declare function pageFindings(bundle: RunBundle): string[];

package/dist/verify/pages.js

@@ -0,0 +1,50 @@
+import { REDACTION_MARKERS } from "../evidence/redaction.js";
+import { isRecord } from "../run/type-guards.js";
+// A recorded page (`items[].page`, `finalPage`) keeps a URL's origin and path only. The text scan
+// finds secret shapes in it as in any trace text, but a query string, a fragment or user info can
+// carry a short token no pattern matches, so a page holding one is a public-safety finding.
+// The markers that can stand for a whole origin, such as a withheld sandbox host.
+const MARKERS = new Set(Object.values(REDACTION_MARKERS));
+// `scheme:` alone (a non-web URL) or `scheme://host[:port]`, with nothing after the host. The URL
+// parser reads a backslash there as a slash, so a backslash counts as a path too.
+const ORIGIN = /^[a-z][a-z0-9+.-]*:(?:\/\/[^/\\?#@]*)?$/i;
+/** What is wrong with a recorded page, or undefined when it holds an origin and a path only. */
+function pageProblem(page) {
+    if (!isRecord(page) || typeof page.origin !== "string" || typeof page.path !== "string")
+        return "is not an origin and a path";
+    if (/[?#]/.test(page.path))
+        return "has a query string or fragment in its path";
+    if (!MARKERS.has(page.origin) && !ORIGIN.test(page.origin))
+        return "has an origin with user info, a path, a query string or a fragment";
+    return undefined;
+}
+/**
+ * One finding per recorded page that holds more than an origin and a path, in each finished
+ * trace's items and summary and each running participant's items. A finding names where the page
+ * is, never what it says.
+ */
+export function pageFindings(bundle) {
+    const findings = [];
+    const check = (where, page) => {
+        if (page === undefined)
+            return;
+        const problem = pageProblem(page);
+        if (problem !== undefined)
+            findings.push(`${where} ${problem}`);
+    };
+    // The shape guard admits items that are not records, so each is read as unknown.
+    const checkItems = (where, items) => {
+        if (!Array.isArray(items))
+            return;
+        items.forEach((item, index) => {
+            if (isRecord(item))
+                check(`${where}[${index}].page`, item.page);
+        });
+    };
+    for (const stream of bundle.streams) {
+        checkItems(`${stream.id} items`, stream.actor?.items);
+        check(`${stream.id} finalPage`, stream.actor?.finalPage);
+        checkItems(`${stream.id} liveActor.items`, stream.liveActor?.items);
+    }
+    return findings;
+}

package/dist/verify/verify.js

@@ -16,6 +16,7 @@ import { runNotFoundMessage } from "../run/run-not-found.js";
 import { actorVerdictConsistencyFindings, noEngagementActorFindings, validateCodexAppServerEvidence, validateTerminalProductEvidence, } from "./actor.js";
 import { invalidRunEvidenceReferences, MAX_REPORTED_FINDINGS, missingLocalEvidenceArtifacts, rawScreenshotPostureWarnings, rawScreenshotStreamIds, redactedShapeFramePaths, scanRunPublicSafetyArtifacts, scanSourceEvidence, streamScreenshotPaths, unscannedMessage, } from "./artifacts.js";
 import { flatContextWarnings } from "./context-growth.js";
+import { pageFindings } from "./pages.js";
 import { runNotFinished } from "./liveness.js";
 import { costAndReceiptFindings } from "./costs.js";
 import { rerunLineageFindings } from "./rerun.js";
@@ -229,7 +230,7 @@ function evidenceArtifactsCheck(shaped, problems) {
 async function loadTraces(runPaths, stored) {
     const scanned = { sensitive: [], opaque: [] };
     if (!isRunBundle(stored))
-        return { bundle: stored, refusedTraces: [], ...scanned };
+        return { bundle: stored, refusedTraces: [], ...scanned, pages: [] };
     // Each trace is source evidence: scanned by the bytes it was joined from, apart from the
     // directory walk and any path exemption the walk makes.
     const { bundle, refused } = await loadStreamTraces(runPaths, stored, {
@@ -239,9 +240,14 @@ async function loadTraces(runPaths, stored) {
                 scanned[scan === "sensitive" ? "sensitive" : "opaque"].push(file);
         },
     });
-    return { bundle, refusedTraces: refused.map((error) => error.message), ...scanned };
+    return {
+        bundle,
+        refusedTraces: refused.map((error) => error.message),
+        ...scanned,
+        pages: pageFindings(bundle),
+    };
 }
-/** The trace scan's results, beside the walk's: each file named once. */
+/** The trace scan's results, beside the walk's: each file named once, then each page finding. */
 function addTraceScan(traces, findings, unscanned) {
     for (const file of traces.sensitive)
         if (!findings.includes(`sensitive text ${file}`))
@@ -249,6 +255,7 @@ function addTraceScan(traces, findings, unscanned) {
     for (const file of traces.opaque)
         if (!unscanned.files.includes(file))
             unscanned.files.push(file);
+    findings.push(...traces.pages);
 }
 /** The top-level run.json sections the shape guard requires. */
 const REQUIRED_SECTIONS = [

package/docs/architecture/actor-contract.md

@@ -167,6 +167,7 @@ export interface ActorTraceItem {
   command?: { text?: string; cwd?: string; exitCode?: number; outputTail?: string };
   screenshotRef?: { path: string; redaction: "blurred" | "ocr_scrubbed" | "none" };
   text?: string; // redacted
+  page?: { origin: string; path: string }; // computer-use screenshot items; redacted, no query
 }
 
 export interface ActorCapabilities {
@@ -204,6 +205,7 @@ export interface ActorTrace {
   ids: { sessionId?: string; threadId?: string; turnId?: string; model?: string };
   counts: Record<string, number>;
   items: ActorTraceItem[];
+  finalPage?: { origin: string; path: string }; // computer-use: the last observation's page
   tokenUsage?: { input?: number; output?: number; total?: number; costUsd?: number };
   estimatedCost?: ActorEstimatedCost; // humanish.actor-estimated-cost.v1 (additive)
   capabilities: ActorCapabilities;

package/docs/architecture/external-public-shared-world.md

@@ -120,7 +120,10 @@ The runtime `location.href` (and the 6-char code inside it) is never persisted r
 runtime-only; the threaded code flows only into the follower's composed prompt (never a raw bundle
 field) and is scrubbed from all narration once latched; the shared origin and lobby path persist only
 as sha256-16 digests (`publicOriginDigest`, `lobbyConvergenceDigest`). This matches the existing
-e2b-URL / host-digest redaction discipline.
+e2b-URL / host-digest redaction discipline. The computer-use loop records each observation's page
+origin and path by default; the shared-world runner (`participantRunDeps` in
+`src/routes/shared-world/participant-specs.ts`) runs every session with `recordPages: false`, on
+both planes, so no page and no `finalPage` reaches a shared-world trace.
 
 ## Mobile fidelity caveat
 

package/docs/architecture/observer.md

@@ -74,7 +74,16 @@ public-safe metadata.
 
 The browser polls `observer-feed.json` with `no-store` caching: the server's
 projection of the run as `{ data, items }`, observer-data.json's content and the
-items, from one read of the run per poll. Static
+items, from one read of the run per poll. While a participant runs, its entry in
+`items` carries `live`, a cursor `<position>.<generation>.<items>.<bytes>` naming its
+live file (`live/<position>.<generation>.ndjson`) and how far the list goes. The page
+sends the cursors of its last body back as `?after=<cursor>,<cursor>`, and the server
+then reads and sends only the items past each one, marking that entry with
+`liveAfter`, the cursor they follow (`src/observer/feed-cursors.ts`). A cursor for an
+earlier generation, past the index or off a line end gets the participant's full list,
+and so does every participant of a finished run. A tail is checked for line ends and
+its line count; the sha256 run.json records is checked whenever a list is read whole.
+A page that cannot join a body sends no cursors with its next poll. Static
 `file://` opening still works for immutable review, but follow mode is the
 operator path. Agents and CI should use `humanish watch --json --no-open` for
 the same fresh evidence without browser open or a long-running process.

package/docs/contracts/policy.md

@@ -146,6 +146,13 @@ certification that the artifact is free of every class in the policy below. A
 first-class PII/PHI detector is [planned](https://github.com/danielgwilson/humanish/issues/108) and would move the listed
 PII classes from author-responsibility to enforced.
 
+The same scan reads the page each computer-use observation recorded (`items[].page`,
+`finalPage`). verify also reports a page whose path holds a query string or fragment, or whose
+origin holds user info or anything after the host, since such a part can carry a short token no
+pattern matches. The recorder withholds email- and token-shaped path segments
+([schemas.md](schemas.md#actor-trace)); a name or other personal data in a readable path is not
+detected.
+
 Required redaction gates:
 
 - run bundle verification;

package/docs/contracts/run-bundle.md

@@ -332,7 +332,7 @@ An actor trace may include `stopCause` alongside its unchanged `status`,
 `completionReason` and verbatim `reason`. Computer-use sessions distinguish
 `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`, and `scheduled_end`. Absence means the route or
+`provider_refused_prompt`, `harness_aborted`, `usage_unreported`, `scheduled_end`, and `session_cap`. Absence means the route or
 recording did not retain this precise field; it does not mean the participant
 finished.
 
@@ -454,6 +454,36 @@ contain the older requested-screen `stream.viewport` shape without `desktopGeome
 Deterministic Playwright-style adapters remain free to declare a viewport that they also render
 exactly; this hosted-desktop rule does not change that contract.
 
+## Desktop Files
+
+A hosted computer-use participant's stream carries `desktopFiles` when its study gave it
+`participants[].files`: one entry per file confirmed on the desktop before the participant
+started, in the order they landed.
+
+```yaml
+desktopFiles:
+  - as: Downloads/photo.png
+    size: 251
+    sha256: <64 hex characters>
+```
+
+`as` is relative to the desktop user's home folder. `size` is the byte count humanish copied,
+which `files.getInfo` on the desktop matched. `sha256` is the digest of those bytes, read on the
+host before any sandbox existed. The contents and the `from` path are not recorded. A participant
+whose copy failed records the files confirmed before the failure. No `desktopFiles` means no file
+was confirmed on that desktop: the study gave the participant none, the run was a dry run, or the
+copy failed before the first file was confirmed. A copy that failed records a `warn` event of type
+`cua-lab.desktop.files.completed`.
+
+## Participant Time Zone
+
+A computer-use or shared-world participant's stream carries `timeZone`, a tz database name such as
+`Europe/London`, when its study gave it one: `participants[].clock.timeZone`, else
+`actor.clock.timeZone`. Its turns gave the local time in that zone, and on a hosted desktop its
+browser launched with `TZ` set to it. The field records the declared zone, also on a dry run; it is
+not read back from the browser. No `timeZone` means the participant had none, and its hosted
+browser ran in the desktop's UTC.
+
 ## Subject Provenance
 
 `subject` is an optional, additive top-level field: structured provenance for

package/docs/contracts/schemas.md

@@ -210,6 +210,24 @@ The rest of this section names keys by their v3 spelling:
   Public/non-loopback targets still require `policies.allowPublicTargets: true`.
   `target` is mutually exclusive with `entry`: `target` is an absolute app-url
   browser target; `entry` is a shared-world participant's same-origin path;
+- `participants[].files` (computer-use on `execution.target: e2b-desktop` only):
+  1 to 20 `{ from, as }` entries, each a file copied onto that participant's desktop
+  before its browser opens. `from` is relative to the folder that holds the study file
+  (`cwd` for a library config); `as` is relative to the desktop user's home folder.
+  The parser refuses an absolute path, a `.`, `..` or empty part, a backslash, an `as`
+  that starts with `~`, lands in `subject/` or on a name starting with `.humanish`, looks
+  like a secret, a local path or encoded text, repeats another `as` or is its folder,
+  and a `from` the local-tree denylist names in any case (`isLocalTreeDenylisted` in
+  `src/subject/local-tree-archive.ts`). The route also refuses an `as` that holds a
+  value from the run's environment, such as a key. The route reads each distinct `from` once, before
+  any sandbox and on dry runs too, with `readContainedRegularFile`: a missing file, a
+  folder, a symbolic or hard link, a path out of the folder, a file above 10 MiB, more
+  than 25 MiB for one participant or 100 MiB of distinct files for the study is
+  refused with `HUMANISH_COMPUTER_USE_DESKTOP_FILES_INVALID` (`readDesktopFiles` in
+  `src/study/desktop-files.ts`). Each file
+  is written with the E2B SDK's `files.write` and its `files.getInfo` size must match, or
+  the participant fails before its first turn. The stream records `desktopFiles`
+  ([run-bundle.md](run-bundle.md#desktop-files)). Other routes refuse the field;
 - a `participants` entry with `count: n` (computer-use E2B route): a group of
   repeated participants. It needs an `id` and the parser expands it to
   `<id>-01` … `<id>-NN`, even when n is 1, before the engine runs (`viewer-01`,
@@ -229,23 +247,51 @@ The rest of this section names keys by their v3 spelling:
   against the sandbox ceiling. A rerun starts its selected participants together;
 - `participants[].endAfterMs` and `windDownMs` (computer-use only): when the participant's
   session ends, in whole milliseconds on the `startAfterMs` clock and after its start, and how
-  long before that each turn tells it the end time and the minutes left (default 600,000).
+  long before that each turn tells it the end time and the minutes left (default a quarter of
+  the window, at most 600,000; `participantSchedule` in `src/study/arrivals.ts`).
   Refused: an end at or before the start, a `windDownMs` without `endAfterMs`, an end on
   `shared-world`, and a window whose sandbox deadline passes the sandbox ceiling. The
-  participant's session budget is its window plus 5 minutes (`participantSessionMs` in
+  participant's session budget is its window plus 5 minutes (`participantSession` in
   `src/study/arrivals.ts`) in place of `execution.timeoutMs`, and its sandbox deadline adds the
   route's headroom to that. At the end the loop requests the closing report (`debrief.trigger:
-  scheduled_end`) and the session ends `goal_satisfied` with `stopCause: scheduled_end`. Before
+  scheduled_end`) and the session ends `goal_satisfied` with `stopCause: scheduled_end`. The
+  outcome an accepted report declares, its `outcome` field or the first line of its summary that
+  is not a `>` blockquote, is the trace's `declaredOutcome`. The blocker rule reads a declared
+  `reached` or `blocked` before the summary, and after a declared `not_reached` it reads the
+  summary. A participant that passes without declaring `reached` counts in the review's
+  `participants.ranUntilEnd`, and its completion labels say it ran until its scheduled end. Before
   the end, a turn that requests no action does not end the session: the trace records a
   `participant ended before its scheduled end` notice, the next request says the time left, and
   the turn counts toward the idle backstop. Before the end, a turn that only waits or takes
   screenshots counts toward neither backstop streak (`advanceBackstop`'s `waitingIsTheTask`). The
   plan entry carries `endAfterMs`, and `study check` prints a `windows` row;
+- `participants[].maxSessionMs` (computer-use only, also on `count:` groups): the longest the
+  participant's session lasts, in whole milliseconds from 1 to 86,400,000, counted from the start
+  of its own session. `windDownMs` applies to it as to `endAfterMs`. Refused: a value outside that
+  range, `maxSessionMs` beside `endAfterMs` on one participant, `maxSessionMs` on `shared-world`,
+  and a cap whose sandbox deadline passes the sandbox ceiling. The session budget is the cap plus
+  5 minutes (`participantSessionMs`) in place of `execution.timeoutMs`, and the schedule holds the
+  participant's slot that long. The route reads the cap's end when the session starts
+  (`participantEnd` in `src/study/arrivals.ts`, `participantClock` in
+  `src/routes/computer-use/participant-model.ts`) and passes it to the loop as
+  `clock.end` with `kind: session_cap`. The participant may end its session before the cap, and
+  its waiting turns count toward the backstops. At the cap the loop requests the closing report
+  (`debrief.trigger: session_cap`) and the session ends `goal_satisfied` with
+  `stopCause: session_cap`, its report's declared outcome read as at a scheduled end. The plan
+  entry carries `maxSessionMs`, and the plan line shows
+  `cap=<duration>`;
 - `participants[].idleWaitMs` (computer-use and shared-world, also on `count:` groups): this
   participant's `actor.idleWaitMs`, in the same range and refused above an explicit
   `actor.maxWaitMs` (`waitLimitValidationReason`). Its trace records it in `waitSettings`;
-- `actor.clock.timeZone` (computer-use): a tz database time zone name, such as `Europe/London`. Each turn's context hint carries
-  the local time in it, and a scheduled end is given in it (UTC without it);
+- `actor.clock.timeZone` (computer-use and shared-world): a tz database time zone name, such as `Europe/London`. Each turn's context hint carries
+  the local time in it, and a scheduled end or session cap is given in it (UTC without it). On a hosted desktop the
+  participant's browser launches with `TZ` set to it (`openParticipantSurface` in
+  `src/routes/computer-use/e2b-desktop/start.ts`). `parseClock` in `src/study/parse/clock.ts` refuses a name Intl does not know, a
+  UTC offset and a case variant of Intl's spelling, which Chrome's ICU reads as UTC or `Etc/Unknown`. The computer-use planner
+  refuses a zone on the local runtime and the in-process route with `HUMANISH_COMPUTER_USE_TIME_ZONE_UNSUPPORTED`;
+- `participants[].clock.timeZone` (computer-use and shared-world, also on `count:` groups): this participant's `actor.clock`,
+  with the same rule. The plan's `limits.timeZone` is the participant's zone, else the actor's. `study check` prints a
+  `time zones` row, and each participant's stream in `run.json` records `timeZone`;
 - `execution.concurrency` (computer-use E2B routes, including shared-world): a
   cap on participants in flight at once. When omitted, every participant runs
   simultaneously: both routes resolve it when they plan, from the final participant count
@@ -253,16 +299,21 @@ The rest of this section names keys by their v3 spelling:
   `HUMANISH_E2B_MAX_CONCURRENT_SANDBOXES` sandboxes at once (20 when unset; a provisioned
   shared world's app sandbox counts against it), so a larger roster runs in waves and the plan
   records a warning naming the setting. A declared value above that limit is refused at plan
-  time. Total sessions and spend are identical either way; only wall-clock
-  and simultaneity differ. Declaring a value below the participant count runs participants in
+  time, unless `HUMANISH_CUA_MAX_CONCURRENCY` lowers it first; the limit then lowers what is
+  left as it does an undeclared default. Total sessions and spend are identical either way; only
+  wall-clock and simultaneity differ. Declaring a value below the participant count runs participants in
   waves and emits a warning saying so, because a green waved run is otherwise
   indistinguishable from the all-live run the author meant. Shared-world studies
   need at least 2 (the host and a follower are live together); `concurrency: 1`
   there is refused at parse, since the sequential turn-taking route was removed
   in 0.106.0. The env override
   `HUMANISH_CUA_MAX_CONCURRENCY` may only lower the effective bound, never
-  raise concurrent paid desktops, and a lowering is recorded on
-  the plan (`envLoweredConcurrencyFrom`). Inert (warned) on other routes.
+  raise concurrent paid desktops. The plan applies it before the E2B limit, on every
+  computer-use desktop and on shared-world, so the schedule, `study check` and the late-start
+  warnings use the lowered count; the plan records a warning and, on computer-use,
+  `envLoweredConcurrencyFrom`. When the E2B limit lowers the count further, the plan records
+  the E2B limit's warning instead. A shared world refuses a value under 2. Inert
+  (warned) on other routes.
   `execution.timeoutMs` is the per-participant session budget on this route (semantics
   change: it was the single-session budget pre-fan-out); there is no run-level
   wall clock. `policies.allowPublicTargets` cannot combine with N>1 against one
@@ -1011,6 +1062,32 @@ Core-owned fields:
   click-like `ui_action` items, structured `coord` (`x`/`y`). Both are additive:
   absent on older bundles and non-stamping producers, and absence means
   "timing/position unrecorded", never zero
+- optional `items[].page` and `finalPage` (`{ origin, path }`, `TracePage` in
+  `src/actors/contract.ts`): where a computer-use participant's browser was. The loop puts `page`
+  on the `screenshot` item of each observation that read a URL: `turn-00-start` is the page before
+  any action, `turn-01` the page after turn 1's actions, and dwell frames have their own.
+  `finalPage` is the page of the session's last observation, which is a closing observation with
+  no item when tasks are declared; it is absent when that observation read no URL. The screenshot
+  items with a `page`, in item order, then `finalPage`, list the participant's path through the
+  app. `origin` is the URL's scheme, host and port; `path` is its percent-encoded path. A query
+  string, fragment and user info are never kept, and a non-web URL keeps its scheme only
+  (`{ origin: "about:", path: "" }`). Redaction (`tracePage` in `src/evidence/trace-page.ts`):
+  a path segment becomes `[REDACTED_URL_PART]` when it percent-encodes a letter, digit, `-`, `.`,
+  `_`, `~` or `%`, or when any decoded reading of it is email-shaped, holds a run of 16 or more letters,
+  digits, `-` and `_` with a piece of 8 or more characters mixing letters and digits, or changes
+  under the trace text redaction (the study's secrets, then `redactText`). The whole path then
+  goes through that redaction, is cut to 1024 characters ending `[TRUNCATED]`, and is withheld
+  whole when verify's trace scan would still read it as sensitive or opaque. A host label
+  shaped like that token run becomes `[REDACTED_URL_PART]`, then the origin goes through the same
+  redaction (an E2B sandbox host becomes `[REDACTED_SECRET]`). When origin and path together
+  still change under that redaction (a study secret that is a whole link), both become
+  `[REDACTED_URL_PART]`. A token shorter than 16 characters, an
+  all-digit id and personal data in readable words stay, so the sharing rules for synthetic data
+  still apply. Pages come from the browser-state probe, which hosted runs have on Chrome and
+  Chromium only; a Firefox participant, or one whose probe is unavailable, has screenshots without
+  pages. The local browser route and the shared-world route record none. verify reports a page
+  whose path holds `?` or `#`, or whose origin is neither a redaction marker nor a scheme with an
+  optional host and port, as a public-safety finding. Both fields are additive; absence means "page not recorded"
 - optional `modelSettings` (`humanish.model-settings.v1`): how the model was
   asked to run, alongside `ids.model` which says which model it was.
   `reasoningEffort` records the value the request actually carried,
@@ -1845,8 +1922,13 @@ verification or maintainer acceptance.
 the run passed also reads `run.json`'s `outcome.ok` ([Run Outcome](run-bundle.md#run-outcome)):
 a run whose execution failed shows as failed beside a `pass` verdict. `participants.reachedGoal` retains the count of
 recorded successful sessions; it is not an independent adjudication of their
-claims. Computer-use review and Observer labels distinguish a participant's
-reported completion from a recorded `stopWhen` or dwell condition match. A
+claims. A computer-use session that passed at its scheduled end or session cap
+counts there only when its participant declared `reached`; otherwise it counts
+in `participants.ranUntilEnd`, present when above 0. Bundles written before
+`ranUntilEnd` existed counted it in `reachedGoal`, and a re-read keeps that
+count. Computer-use review and Observer labels distinguish a participant's
+reported completion from a recorded `stopWhen` or dwell condition match, and
+from a pass at a clock end without a declared reach. A
 condition match establishes that condition, not every aspect of the mission.
 Missing or malformed completion evidence is labeled unavailable. Other actor
 routes retain their own completion semantics. Re-reading a historical review

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "humanish",
-  "version": "0.125.0",
+  "version": "0.127.0",
   "description": "Synthetic user research for apps, CLIs, and agent-facing product flows.",
   "keywords": [
     "cli",
@@ -96,7 +96,7 @@
     "comms:agentmail:contract": "node --import tsx scripts/agentmail-contract-check.mjs",
     "format": "oxfmt",
     "format:check": "oxfmt --check",
-    "lint": "node scripts/check-lint-cap.mjs --max-warnings=424",
+    "lint": "node scripts/check-lint-cap.mjs --max-warnings=411",
     "knip": "knip",
     "prose:check": "node scripts/check-code-prose.mjs",
     "vocabulary:check": "tsx scripts/check-retired-words.ts",